feat(auth): add DB-backed login, token management, and idempotent auth migration

app/api/auth_routes.py

@@ -0,0 +1,114 @@
+"""Authentication API routes."""
+
+from __future__ import annotations
+
+from typing import NoReturn
+
+from fastapi import APIRouter, Depends, HTTPException, Response, status
+
+from app.core.auth import AuthContext, require_read
+from app.domain.models import AuthToken, User
+from app.schemas.auth import AuthTokenResponse, CreateClientTokenRequest, IssuedClientTokenResponse, LoginRequest, TokenResponse
+from app.schemas.user import UserResponse
+from app.services.auth_service import AuthService, IssuedClientToken, LoginResult, get_auth_service
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+
+def _to_user_response(user: User) -> UserResponse:
+    return UserResponse(
+        id=user.id,
+        username=user.username,
+        email=user.email,
+        permission=user.permission,
+        is_active=user.is_active,
+        created_at=user.created_at,
+        updated_at=user.updated_at,
+        last_login_at=user.last_login_at,
+    )
+
+
+def _to_auth_token_response(token: AuthToken) -> AuthTokenResponse:
+    return AuthTokenResponse(
+        id=token.id,
+        user_id=token.user_id,
+        name=token.name,
+        token_prefix=token.token_prefix,
+        permission=token.permission,
+        token_type=token.token_type,
+        expires_at=token.expires_at,
+        last_used_at=token.last_used_at,
+        revoked_at=token.revoked_at,
+        created_at=token.created_at,
+    )
+
+
+def _to_login_response(result: LoginResult) -> TokenResponse:
+    return TokenResponse(
+        access_token=result.token,
+        expires_at=result.auth_token.expires_at,
+        permission=result.auth_token.permission,
+        user=_to_user_response(result.user),
+    )
+
+
+def _to_issued_token_response(result: IssuedClientToken) -> IssuedClientTokenResponse:
+    return IssuedClientTokenResponse(
+        token=result.token,
+        auth_token=_to_auth_token_response(result.auth_token),
+    )
+
+
+def _raise_auth_error(exc: ValueError) -> NoReturn:
+    detail = str(exc)
+    if "잘못된 사용자명 또는 비밀번호" in detail:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=detail) from exc
+    if "초과" in detail:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=detail) from exc
+    if "찾을 수 없습니다" in detail:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=detail) from exc
+    raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=detail) from exc
+
+
+@router.post("/login", response_model=TokenResponse)
+def login(payload: LoginRequest, service: AuthService = Depends(get_auth_service)) -> TokenResponse:
+    try:
+        return _to_login_response(service.login(payload))
+    except ValueError as exc:
+        _raise_auth_error(exc)
+
+
+@router.get("/tokens", response_model=list[AuthTokenResponse], dependencies=[Depends(require_read)])
+def list_tokens(
+    auth_context: AuthContext = Depends(require_read),
+    service: AuthService = Depends(get_auth_service),
+) -> list[AuthTokenResponse]:
+    try:
+        return [_to_auth_token_response(token) for token in service.list_tokens(auth_context)]
+    except ValueError as exc:
+        _raise_auth_error(exc)
+
+
+@router.post("/tokens", response_model=IssuedClientTokenResponse, status_code=status.HTTP_201_CREATED, dependencies=[Depends(require_read)])
+def create_token(
+    payload: CreateClientTokenRequest,
+    auth_context: AuthContext = Depends(require_read),
+    service: AuthService = Depends(get_auth_service),
+) -> IssuedClientTokenResponse:
+    try:
+        return _to_issued_token_response(service.issue_client_token(auth_context, payload))
+    except ValueError as exc:
+        _raise_auth_error(exc)
+
+
+@router.delete("/tokens/{token_id}", status_code=status.HTTP_204_NO_CONTENT, dependencies=[Depends(require_read)])
+def revoke_token(
+    token_id: str,
+    auth_context: AuthContext = Depends(require_read),
+    service: AuthService = Depends(get_auth_service),
+) -> Response:
+    try:
+        service.revoke_token(auth_context, token_id)
+    except ValueError as exc:
+        _raise_auth_error(exc)
+    return Response(status_code=status.HTTP_204_NO_CONTENT)

app/api/portfolios.py

@@ -1,8 +1,10 @@
 """Portfolio API routes."""
 
-from fastapi import APIRouter, Depends, Response, status
+from fastapi import APIRouter, Depends, Request, Response, status
 
-from app.core.auth import require_admin, require_read, require_trade_write
+from app.core.auth import Permission, authorize_request
+from app.core.config import Settings, get_settings
+from app.repositories.factory import get_portfolio_repository_from_settings
 from app.schemas.portfolio import (
     BuyRequest,
     CreatePortfolioRequest,
@@ -14,101 +16,179 @@ from app.schemas.portfolio import (
     TransferRequest,
     UpdatePortfolioRequest,
 )
-from app.services.portfolio_service import PortfolioService, get_portfolio_service
+from app.services.portfolio_service import PortfolioService
 
 router = APIRouter(prefix="/portfolios", tags=["portfolios"])
 
 
-@router.get("", response_model=list[PortfolioListItem], dependencies=[Depends(require_read)])
+def _get_service(settings: Settings) -> tuple[PortfolioService, object]:
+    repository = get_portfolio_repository_from_settings(settings)
+    return PortfolioService(repository), repository
+
+
+def _close_repository(repository: object) -> None:
+    if callable(getattr(type(repository), "close", None)):
+        repository.close()
+
+
+@router.get("", response_model=list[PortfolioListItem])
 def list_portfolios(
+    request: Request,
     broker: str | None = None,
     status_filter: str | None = None,
-    service: PortfolioService = Depends(get_portfolio_service),
+    settings: Settings = Depends(get_settings),
 ) -> list[PortfolioListItem]:
-    return service.list_portfolios(broker=broker, status=status_filter)
+    authorize_request(Permission.READ, request, settings)
+    service, repository = _get_service(settings)
+    try:
+        return service.list_portfolios(broker=broker, status=status_filter)
+    finally:
+        _close_repository(repository)
 
 
-@router.get("/{portfolio_id}", response_model=PortfolioDetailResponse, dependencies=[Depends(require_read)])
+@router.get("/{portfolio_id}", response_model=PortfolioDetailResponse)
 def get_portfolio(
     portfolio_id: str,
+    request: Request,
+    *,
     recent_trades: int = 5,
-    service: PortfolioService = Depends(get_portfolio_service),
+    settings: Settings = Depends(get_settings),
 ) -> PortfolioDetailResponse:
-    return service.get_portfolio_status(portfolio_id=portfolio_id, recent_trades=recent_trades)
+    authorize_request(Permission.READ, request, settings)
+    service, repository = _get_service(settings)
+    try:
+        return service.get_portfolio_status(portfolio_id=portfolio_id, recent_trades=recent_trades)
+    finally:
+        _close_repository(repository)
 
 
 @router.post(
     "",
     response_model=PortfolioDetailResponse,
     status_code=status.HTTP_201_CREATED,
-    dependencies=[Depends(require_trade_write)],
 )
 def create_portfolio(
     payload: CreatePortfolioRequest,
-    service: PortfolioService = Depends(get_portfolio_service),
+    request: Request,
+    *,
+    settings: Settings = Depends(get_settings),
 ) -> PortfolioDetailResponse:
-    return service.create_portfolio(payload)
+    authorize_request(Permission.TRADE_WRITE, request, settings)
+    service, repository = _get_service(settings)
+    try:
+        return service.create_portfolio(payload)
+    finally:
+        _close_repository(repository)
 
 
-@router.patch("/{portfolio_id}", response_model=PortfolioDetailResponse, dependencies=[Depends(require_trade_write)])
+@router.patch("/{portfolio_id}", response_model=PortfolioDetailResponse)
 def update_portfolio(
     portfolio_id: str,
     payload: UpdatePortfolioRequest,
-    service: PortfolioService = Depends(get_portfolio_service),
+    request: Request,
+    *,
+    settings: Settings = Depends(get_settings),
 ) -> PortfolioDetailResponse:
-    return service.update_portfolio(portfolio_id, payload)
+    authorize_request(Permission.TRADE_WRITE, request, settings)
+    service, repository = _get_service(settings)
+    try:
+        return service.update_portfolio(portfolio_id, payload)
+    finally:
+        _close_repository(repository)
 
 
-@router.post("/{portfolio_id}/buy", response_model=PortfolioDetailResponse, dependencies=[Depends(require_trade_write)])
+@router.post("/{portfolio_id}/buy", response_model=PortfolioDetailResponse)
 def buy_portfolio_asset(
     portfolio_id: str,
     payload: BuyRequest,
-    service: PortfolioService = Depends(get_portfolio_service),
+    request: Request,
+    *,
+    settings: Settings = Depends(get_settings),
 ) -> PortfolioDetailResponse:
-    return service.buy(portfolio_id, payload)
+    authorize_request(Permission.TRADE_WRITE, request, settings)
+    service, repository = _get_service(settings)
+    try:
+        return service.buy(portfolio_id, payload)
+    finally:
+        _close_repository(repository)
 
 
-@router.post("/{portfolio_id}/sell", response_model=PortfolioDetailResponse, dependencies=[Depends(require_trade_write)])
+@router.post("/{portfolio_id}/sell", response_model=PortfolioDetailResponse)
 def sell_portfolio_asset(
     portfolio_id: str,
     payload: SellRequest,
-    service: PortfolioService = Depends(get_portfolio_service),
+    request: Request,
+    *,
+    settings: Settings = Depends(get_settings),
 ) -> PortfolioDetailResponse:
-    return service.sell(portfolio_id, payload)
+    authorize_request(Permission.TRADE_WRITE, request, settings)
+    service, repository = _get_service(settings)
+    try:
+        return service.sell(portfolio_id, payload)
+    finally:
+        _close_repository(repository)
 
 
-@router.post("/{portfolio_id}/invest", response_model=PortfolioDetailResponse, dependencies=[Depends(require_trade_write)])
+@router.post("/{portfolio_id}/invest", response_model=PortfolioDetailResponse)
 def invest_buffer(
     portfolio_id: str,
     payload: InvestRequest,
-    service: PortfolioService = Depends(get_portfolio_service),
+    request: Request,
+    *,
+    settings: Settings = Depends(get_settings),
 ) -> PortfolioDetailResponse:
-    return service.invest(portfolio_id, payload)
+    authorize_request(Permission.TRADE_WRITE, request, settings)
+    service, repository = _get_service(settings)
+    try:
+        return service.invest(portfolio_id, payload)
+    finally:
+        _close_repository(repository)
 
 
-@router.post("/{portfolio_id}/transfer", response_model=PortfolioDetailResponse, dependencies=[Depends(require_trade_write)])
+@router.post("/{portfolio_id}/transfer", response_model=PortfolioDetailResponse)
 def transfer_buffer(
     portfolio_id: str,
     payload: TransferRequest,
-    service: PortfolioService = Depends(get_portfolio_service),
+    request: Request,
+    *,
+    settings: Settings = Depends(get_settings),
 ) -> PortfolioDetailResponse:
-    return service.transfer(portfolio_id, payload)
+    authorize_request(Permission.TRADE_WRITE, request, settings)
+    service, repository = _get_service(settings)
+    try:
+        return service.transfer(portfolio_id, payload)
+    finally:
+        _close_repository(repository)
 
 
-@router.post("/{portfolio_id}/reset", response_model=PortfolioDetailResponse, dependencies=[Depends(require_trade_write)])
+@router.post("/{portfolio_id}/reset", response_model=PortfolioDetailResponse)
 def reset_portfolio(
     portfolio_id: str,
     payload: ResetPortfolioRequest,
-    service: PortfolioService = Depends(get_portfolio_service),
+    request: Request,
+    *,
+    settings: Settings = Depends(get_settings),
 ) -> PortfolioDetailResponse:
-    return service.reset(portfolio_id, payload)
+    authorize_request(Permission.TRADE_WRITE, request, settings)
+    service, repository = _get_service(settings)
+    try:
+        return service.reset(portfolio_id, payload)
+    finally:
+        _close_repository(repository)
 
 
-@router.delete("/{portfolio_id}", status_code=status.HTTP_204_NO_CONTENT, dependencies=[Depends(require_admin)])
+@router.delete("/{portfolio_id}", status_code=status.HTTP_204_NO_CONTENT)
 def delete_portfolio(
     portfolio_id: str,
+    request: Request,
+    *,
     keep_ledger: bool = False,
-    service: PortfolioService = Depends(get_portfolio_service),
+    settings: Settings = Depends(get_settings),
 ) -> Response:
-    service.delete(portfolio_id, keep_ledger=keep_ledger)
+    authorize_request(Permission.ADMIN, request, settings)
+    service, repository = _get_service(settings)
+    try:
+        service.delete(portfolio_id, keep_ledger=keep_ledger)
+    finally:
+        _close_repository(repository)
     return Response(status_code=status.HTTP_204_NO_CONTENT)

app/api/strategy_sets.py

@@ -2,24 +2,37 @@
 
 from fastapi import APIRouter, Depends, Response, status
 
-from app.core.auth import require_read, require_trade_write
+from app.core.auth import AuthContext, require_read, require_trade_write
+from app.core.config import Settings, get_settings
+from app.repositories.factory import get_portfolio_repository_from_settings
 from app.schemas.portfolio import CreateStrategySetRequest, StrategySetResponse, UpdateStrategySetRequest
-from app.services.strategy_set_service import StrategySetService, get_strategy_set_repository
-
-
-def get_strategy_set_service(repository=Depends(get_strategy_set_repository)) -> StrategySetService:
-    return StrategySetService(repository)
+from app.services.strategy_set_service import StrategySetService
 
 
 router = APIRouter(prefix="/strategy-sets", tags=["strategy-sets"])
 
 
-@router.get("", response_model=list[StrategySetResponse], dependencies=[Depends(require_read)])
+def _get_service(settings: Settings) -> tuple[StrategySetService, object]:
+    repository = get_portfolio_repository_from_settings(settings)
+    return StrategySetService(repository), repository
+
+
+def _close_repository(repository: object) -> None:
+    if callable(getattr(type(repository), "close", None)):
+        repository.close()
+
+
+@router.get("", response_model=list[StrategySetResponse])
 def list_strategy_sets(
-    service: StrategySetService = Depends(get_strategy_set_service),
+    _auth: AuthContext = Depends(require_read),
+    settings: Settings = Depends(get_settings),
 ) -> list[StrategySetResponse]:
     """List all strategy sets."""
-    strategy_sets = service.list()
+    service, repository = _get_service(settings)
+    try:
+        strategy_sets = service.list()
+    finally:
+        _close_repository(repository)
     return [
         StrategySetResponse(
             id=ss.id,
@@ -32,13 +45,18 @@ def list_strategy_sets(
     ]
 
 
-@router.post("", response_model=StrategySetResponse, status_code=status.HTTP_201_CREATED, dependencies=[Depends(require_trade_write)])
+@router.post("", response_model=StrategySetResponse, status_code=status.HTTP_201_CREATED)
 def create_strategy_set(
     payload: CreateStrategySetRequest,
-    service: StrategySetService = Depends(get_strategy_set_service),
+    _auth: AuthContext = Depends(require_trade_write),
+    settings: Settings = Depends(get_settings),
 ) -> StrategySetResponse:
     """Create a new strategy set (or return existing if (name, config) pair already exists)."""
-    strategy_set = service.create(payload)
+    service, repository = _get_service(settings)
+    try:
+        strategy_set = service.create(payload)
+    finally:
+        _close_repository(repository)
     return StrategySetResponse(
         id=strategy_set.id,
         name=strategy_set.name,
@@ -48,18 +66,23 @@ def create_strategy_set(
     )
 
 
-@router.patch("/{strategy_set_id}", response_model=StrategySetResponse, dependencies=[Depends(require_trade_write)])
+@router.patch("/{strategy_set_id}", response_model=StrategySetResponse)
 def update_strategy_set(
     strategy_set_id: str,
     payload: UpdateStrategySetRequest,
-    service: StrategySetService = Depends(get_strategy_set_service),
+    _auth: AuthContext = Depends(require_trade_write),
+    settings: Settings = Depends(get_settings),
 ) -> StrategySetResponse:
     """Update a strategy set's name and/or config.
     
     Note: Since strategy sets are identified by (name, config) uniqueness,
     updating may result in a new strategy set ID if name or config changes.
     """
-    strategy_set = service.update(strategy_set_id, payload)
+    service, repository = _get_service(settings)
+    try:
+        strategy_set = service.update(strategy_set_id, payload)
+    finally:
+        _close_repository(repository)
     return StrategySetResponse(
         id=strategy_set.id,
         name=strategy_set.name,
@@ -69,10 +92,11 @@ def update_strategy_set(
     )
 
 
-@router.delete("/{strategy_set_id}", status_code=status.HTTP_204_NO_CONTENT, dependencies=[Depends(require_trade_write)])
+@router.delete("/{strategy_set_id}", status_code=status.HTTP_204_NO_CONTENT)
 def delete_strategy_set(
     strategy_set_id: str,
-    service: StrategySetService = Depends(get_strategy_set_service),
+    _auth: AuthContext = Depends(require_trade_write),
+    settings: Settings = Depends(get_settings),
 ) -> Response:
     """Delete a strategy set.
     
@@ -80,7 +104,11 @@ def delete_strategy_set(
     Returns 409 Conflict if the strategy set is in use by any portfolio.
     """
     try:
-        service.delete(strategy_set_id)
+        service, repository = _get_service(settings)
+        try:
+            service.delete(strategy_set_id)
+        finally:
+            _close_repository(repository)
     except ValueError as e:
         # If strategy set is in use, return 409 Conflict
         raise ValueError(str(e)) from e

app/api/users.py

@@ -1,26 +1,40 @@
 """User management API routes."""
 
 from __future__ import annotations
-
 from typing import NoReturn
 
 from fastapi import APIRouter, Depends, HTTPException, Response, status
 
-from app.core.auth import require_admin
+from app.core.auth import AuthContext, require_admin
+from app.core.config import Settings, get_settings
 from app.domain.models import User
+from app.repositories.factory import get_portfolio_repository_from_settings
 from app.schemas.user import CreateUserRequest, UpdateUserRequest, UserResponse
-from app.services.user_service import UserService, get_user_service
+from app.services.user_service import UserService
 
 router = APIRouter(prefix="/users", tags=["users"])
 
 
+def _get_service(settings: Settings) -> tuple[UserService, object]:
+    repository = get_portfolio_repository_from_settings(settings)
+    return UserService(repository), repository
+
+
+def _close_repository(repository: object) -> None:
+    if callable(getattr(type(repository), "close", None)):
+        repository.close()
+
+
 def _to_user_response(user: User) -> UserResponse:
     return UserResponse(
         id=user.id,
         username=user.username,
         email=user.email,
+        permission=user.permission,
+        is_active=user.is_active,
         created_at=user.created_at,
         updated_at=user.updated_at,
+        last_login_at=user.last_login_at,
     )
 
 
@@ -33,43 +47,79 @@ def _raise_user_error(exc: ValueError) -> NoReturn:
     raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=detail) from exc
 
 
-@router.get("", response_model=list[UserResponse], dependencies=[Depends(require_admin)])
-def list_users(service: UserService = Depends(get_user_service)) -> list[UserResponse]:
-    return [_to_user_response(user) for user in service.list()]
-
-
-@router.get("/{user_id}", response_model=UserResponse, dependencies=[Depends(require_admin)])
-def get_user(user_id: str, service: UserService = Depends(get_user_service)) -> UserResponse:
+@router.get("", response_model=list[UserResponse])
+def list_users(
+    _auth: AuthContext = Depends(require_admin),
+    settings: Settings = Depends(get_settings),
+) -> list[UserResponse]:
+    service, repository = _get_service(settings)
     try:
-        return _to_user_response(service.get(user_id))
+        return [_to_user_response(user) for user in service.list()]
+    finally:
+        _close_repository(repository)
+
+
+@router.get("/{user_id}", response_model=UserResponse)
+def get_user(
+    user_id: str,
+    _auth: AuthContext = Depends(require_admin),
+    settings: Settings = Depends(get_settings),
+) -> UserResponse:
+    try:
+        service, repository = _get_service(settings)
+        try:
+            return _to_user_response(service.get(user_id))
+        finally:
+            _close_repository(repository)
     except ValueError as exc:
         _raise_user_error(exc)
 
 
-@router.post("", response_model=UserResponse, status_code=status.HTTP_201_CREATED, dependencies=[Depends(require_admin)])
-def create_user(payload: CreateUserRequest, service: UserService = Depends(get_user_service)) -> UserResponse:
+@router.post("", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+def create_user(
+    payload: CreateUserRequest,
+    _auth: AuthContext = Depends(require_admin),
+    settings: Settings = Depends(get_settings),
+) -> UserResponse:
     try:
-        return _to_user_response(service.create(payload))
+        service, repository = _get_service(settings)
+        try:
+            return _to_user_response(service.create(payload))
+        finally:
+            _close_repository(repository)
     except ValueError as exc:
         _raise_user_error(exc)
 
 
-@router.patch("/{user_id}", response_model=UserResponse, dependencies=[Depends(require_admin)])
+@router.patch("/{user_id}", response_model=UserResponse)
 def update_user(
     user_id: str,
     payload: UpdateUserRequest,
-    service: UserService = Depends(get_user_service),
+    _auth: AuthContext = Depends(require_admin),
+    settings: Settings = Depends(get_settings),
 ) -> UserResponse:
     try:
-        return _to_user_response(service.update(user_id, payload))
+        service, repository = _get_service(settings)
+        try:
+            return _to_user_response(service.update(user_id, payload))
+        finally:
+            _close_repository(repository)
     except ValueError as exc:
         _raise_user_error(exc)
 
 
-@router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT, dependencies=[Depends(require_admin)])
-def delete_user(user_id: str, service: UserService = Depends(get_user_service)) -> Response:
+@router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_user(
+    user_id: str,
+    _auth: AuthContext = Depends(require_admin),
+    settings: Settings = Depends(get_settings),
+) -> Response:
     try:
-        service.delete(user_id)
+        service, repository = _get_service(settings)
+        try:
+            service.delete(user_id)
+        finally:
+            _close_repository(repository)
     except ValueError as exc:
         _raise_user_error(exc)
     return Response(status_code=status.HTTP_204_NO_CONTENT)

app/cli/commands/health.py

@@ -100,5 +100,5 @@ def register_health_commands(app: typer.Typer) -> None:
                 for key, value in health.items():
                     app_context.console.print(f"{key}: {value}")
         finally:
-            if hasattr(repository, "close"):
+            if callable(getattr(type(repository), "close", None)):
                 repository.close()

app/cli/commands/portfolio.py

@@ -40,7 +40,7 @@ def _with_service(ctx: typer.Context, callback):
         result = execute_command(app_context.console, callback=lambda: callback(service, app_context))
         return result
     finally:
-        if hasattr(repository, "close"):
+        if callable(getattr(type(repository), "close", None)):
             repository.close()
 
 

app/cli/commands/strategy.py

@@ -19,7 +19,7 @@ def _with_service(ctx: typer.Context, callback):
         result = execute_command(app_context.console, callback=lambda: callback(service, app_context))
         return result
     finally:
-        if hasattr(repository, "close"):
+        if callable(getattr(type(repository), "close", None)):
             repository.close()
 
 

app/cli/commands/user.py

@@ -20,7 +20,7 @@ def _with_service(ctx: typer.Context, callback):
     try:
         return execute_command(app_context.console, callback=lambda: callback(service, app_context))
     finally:
-        if hasattr(repository, "close"):
+        if callable(getattr(type(repository), "close", None)):
             repository.close()
 
 
@@ -29,8 +29,11 @@ def _to_user_response(user) -> UserResponse:
         id=user.id,
         username=user.username,
         email=user.email,
+        permission=user.permission,
+        is_active=user.is_active,
         created_at=user.created_at,
         updated_at=user.updated_at,
+        last_login_at=user.last_login_at,
     )
 
 
@@ -53,14 +56,25 @@ def get_user(
 def create_user(
     ctx: typer.Context,
     username: str = typer.Option(..., help="Username."),
+    password: str = typer.Option(..., help="Initial password."),
     email: str | None = typer.Option(None, help="Email address."),
+    permission: str = typer.Option("read", help="Permission: read, trade-write, admin."),
+    is_active: bool = typer.Option(True, help="Whether the user is active."),
     force: bool = typer.Option(False, "--force", help="Skip confirmation prompt."),
 ) -> None:
     _confirm(force, f"Create user {username}?")
     user = _with_service(
         ctx,
         lambda service, app_context: _to_user_response(
-            service.create(CreateUserRequest(username=username, email=email))
+            service.create(
+                CreateUserRequest(
+                    username=username,
+                    password=password,
+                    email=email,
+                    permission=permission,
+                    is_active=is_active,
+                )
+            )
         ),
     )
     render_output(ctx.obj.console, ctx.obj.output_format, user)
@@ -71,14 +85,26 @@ def update_user(
     ctx: typer.Context,
     user_id: str = typer.Argument(..., help="User identifier."),
     username: str | None = typer.Option(None, help="New username."),
+    password: str | None = typer.Option(None, help="New password."),
     email: str | None = typer.Option(None, help="New email address."),
+    permission: str | None = typer.Option(None, help="New permission."),
+    is_active: bool | None = typer.Option(None, help="Whether the user is active."),
     force: bool = typer.Option(False, "--force", help="Skip confirmation prompt."),
 ) -> None:
     _confirm(force, f"Update user {user_id}?")
     user = _with_service(
         ctx,
         lambda service, app_context: _to_user_response(
-            service.update(user_id, UpdateUserRequest(username=username, email=email))
+            service.update(
+                user_id,
+                UpdateUserRequest(
+                    username=username,
+                    password=password,
+                    email=email,
+                    permission=permission,
+                    is_active=is_active,
+                ),
+            )
         ),
     )
     render_output(ctx.obj.console, ctx.obj.output_format, user)

app/core/auth.py

@@ -4,11 +4,14 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from enum import StrEnum
+from typing import Generator
 
-from fastapi import Depends, HTTPException, status
-from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from fastapi import Depends, HTTPException, Request, status
 
 from app.core.config import Settings, get_settings
+from app.core.security import hash_token
+from app.repositories.factory import get_portfolio_repository_from_settings
+from app.repositories.portfolio_repository import PortfolioRepository
 
 
 class Permission(StrEnum):
@@ -21,9 +24,17 @@ class Permission(StrEnum):
 class AuthContext:
     token: str
     permission: Permission
+    user_id: str | None = None
+    token_id: str | None = None
+    token_source: str = "env"
 
-
-security = HTTPBearer(auto_error=False)
+def get_auth_repository(settings: Settings = Depends(get_settings)) -> Generator[PortfolioRepository, None, None]:
+    repository = get_portfolio_repository_from_settings(settings)
+    try:
+        yield repository
+    finally:
+        if callable(getattr(type(repository), "close", None)):
+            repository.close()
 
 
 def _resolve_permission(token: str, settings: Settings) -> Permission | None:
@@ -36,6 +47,26 @@ def _resolve_permission(token: str, settings: Settings) -> Permission | None:
     return None
 
 
+def _resolve_auth_context(token: str, settings: Settings, repository: PortfolioRepository) -> AuthContext | None:
+    permission = _resolve_permission(token, settings)
+    if permission is not None:
+        return AuthContext(token=token, permission=permission, token_source="env")
+
+    if not settings.db_enabled:
+        return None
+
+    principal = repository.get_token_principal(hash_token(token))
+    if principal is None:
+        return None
+    return AuthContext(
+        token=token,
+        permission=Permission(principal.permission),
+        user_id=principal.user_id,
+        token_id=principal.token_id,
+        token_source="db",
+    )
+
+
 def _has_permission(current: Permission, required: Permission) -> bool:
     if current == Permission.ADMIN:
         return True
@@ -48,28 +79,53 @@ def _has_permission(current: Permission, required: Permission) -> bool:
 
 def require_permission(
     required: Permission,
-    credentials: HTTPAuthorizationCredentials | None = Depends(security),
+    request: Request,
     settings: Settings = Depends(get_settings),
+    repository: PortfolioRepository = Depends(get_auth_repository),
 ) -> AuthContext:
-    if credentials is None or credentials.scheme.lower() != "bearer":
+    return authorize_request(required, request, settings, repository=repository)
+
+
+def authorize_request(
+    required: Permission,
+    request: Request,
+    settings: Settings,
+    *,
+    repository: PortfolioRepository | None = None,
+) -> AuthContext:
+    authorization = request.headers.get("Authorization", "").strip()
+    if not authorization:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Missing bearer token")
+    scheme, _, token = authorization.partition(" ")
+    if scheme.lower() != "bearer" or not token:
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Missing bearer token")
 
-    permission = _resolve_permission(credentials.credentials, settings)
-    if permission is None:
+    managed_repository = repository is None
+    if repository is None:
+        repository = get_portfolio_repository_from_settings(settings)
+
+    try:
+        auth_context = _resolve_auth_context(token, settings, repository)
+    finally:
+        if managed_repository and callable(getattr(type(repository), "close", None)):
+            repository.close()
+
+    if auth_context is None:
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token")
 
-    if not _has_permission(permission, required):
+    if not _has_permission(auth_context.permission, required):
         raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Insufficient permission")
 
-    return AuthContext(token=credentials.credentials, permission=permission)
+    return auth_context
 
 
 def permission_dependency(required: Permission):
     def dependency(
-        credentials: HTTPAuthorizationCredentials | None = Depends(security),
+        request: Request,
         settings: Settings = Depends(get_settings),
+        repository: PortfolioRepository = Depends(get_auth_repository),
     ) -> AuthContext:
-        return require_permission(required, credentials=credentials, settings=settings)
+        return require_permission(required, request=request, settings=settings, repository=repository)
 
     return dependency
 

app/core/config.py

@@ -21,10 +21,15 @@ class Settings(BaseSettings):
     app_version: str = "0.1.0"
     environment: str = "development"
     allowed_origins_raw: str = Field(default="http://localhost:3000", validation_alias="PORTFOLIOHUB_ALLOWED_ORIGINS")
+    bootstrap_username: str = Field(default="", validation_alias="PORTFOLIOHUB_BOOTSTRAP_USERNAME")
+    bootstrap_email: str = Field(default="", validation_alias="PORTFOLIOHUB_BOOTSTRAP_EMAIL")
+    bootstrap_password: str = Field(default="", validation_alias="PORTFOLIOHUB_BOOTSTRAP_PASSWORD")
     read_tokens_raw: str = Field(default="", validation_alias="PORTFOLIOHUB_READ_TOKENS")
     trade_write_tokens_raw: str = Field(default="", validation_alias="PORTFOLIOHUB_TRADE_WRITE_TOKENS")
     admin_tokens_raw: str = Field(default="", validation_alias="PORTFOLIOHUB_ADMIN_TOKENS")
     db_enabled: bool = Field(default=False, validation_alias="PORTFOLIOHUB_DB_ENABLED")
+    session_token_ttl_hours: int = Field(default=12, validation_alias="PORTFOLIOHUB_SESSION_TOKEN_TTL_HOURS")
+    client_token_default_ttl_days: int = Field(default=365, validation_alias="PORTFOLIOHUB_CLIENT_TOKEN_DEFAULT_TTL_DAYS")
 
     # External services configuration
     timescaledb_host: str = Field(default="localhost", validation_alias="TIMESCALEDB_HOST")
@@ -49,6 +54,7 @@ class Settings(BaseSettings):
         env_prefix="PORTFOLIOHUB_",
         case_sensitive=False,
         extra="ignore",
+        populate_by_name=True,
     )
 
     @computed_field
@@ -56,6 +62,24 @@ class Settings(BaseSettings):
     def allowed_origins(self) -> list[str]:
         return [item.strip() for item in self.allowed_origins_raw.split(",") if item.strip()]
 
+    @computed_field
+    @property
+    def bootstrap_user_username(self) -> str | None:
+        normalized = self.bootstrap_username.strip()
+        return normalized or None
+
+    @computed_field
+    @property
+    def bootstrap_user_email(self) -> str | None:
+        normalized = self.bootstrap_email.strip()
+        return normalized or None
+
+    @computed_field
+    @property
+    def bootstrap_user_password(self) -> str | None:
+        normalized = self.bootstrap_password.strip()
+        return normalized or None
+
     @computed_field
     @property
     def read_tokens(self) -> set[str]:

app/core/security.py

@@ -0,0 +1,50 @@
+"""Password hashing and opaque token helpers."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import secrets
+
+
+def hash_password(password: str) -> str:
+    salt = secrets.token_bytes(16)
+    derived = hashlib.scrypt(password.encode("utf-8"), salt=salt, n=16384, r=8, p=1)
+    return "scrypt$16384$8$1${}${}".format(
+        base64.b64encode(salt).decode("ascii"),
+        base64.b64encode(derived).decode("ascii"),
+    )
+
+
+def verify_password(password: str, encoded: str | None) -> bool:
+    if not encoded:
+        return False
+    try:
+        algorithm, n_value, r_value, p_value, salt_encoded, digest_encoded = encoded.split("$", maxsplit=5)
+    except ValueError:
+        return False
+    if algorithm != "scrypt":
+        return False
+    salt = base64.b64decode(salt_encoded.encode("ascii"))
+    expected = base64.b64decode(digest_encoded.encode("ascii"))
+    actual = hashlib.scrypt(
+        password.encode("utf-8"),
+        salt=salt,
+        n=int(n_value),
+        r=int(r_value),
+        p=int(p_value),
+    )
+    return hmac.compare_digest(actual, expected)
+
+
+def generate_token() -> str:
+    return secrets.token_urlsafe(32)
+
+
+def hash_token(token: str) -> str:
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+
+def token_prefix(token: str) -> str:
+    return token[:8]

app/domain/models.py

@@ -21,8 +21,34 @@ class User:
     id: str
     username: str
     email: str | None = None
+    permission: str = "read"
+    is_active: bool = True
+    password_hash: str | None = None
     created_at: datetime | None = None
     updated_at: datetime | None = None
+    last_login_at: datetime | None = None
+
+
+@dataclass
+class AuthToken:
+    id: str
+    user_id: str
+    name: str
+    token_prefix: str
+    permission: str
+    token_type: str
+    expires_at: datetime | None = None
+    last_used_at: datetime | None = None
+    revoked_at: datetime | None = None
+    created_at: datetime | None = None
+
+
+@dataclass
+class TokenPrincipal:
+    token_id: str
+    user_id: str
+    permission: str
+    token_type: str
 
 
 @dataclass

app/main.py

@@ -1,23 +1,63 @@
 """FastAPI application entrypoint."""
 
+from contextlib import asynccontextmanager
+from typing import Callable
+
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
 from app.api.health import router as health_router
+from app.api.auth_routes import router as auth_router
 from app.api.portfolios import router as portfolio_router
 from app.api.strategy_sets import router as strategy_sets_router
 from app.api.users import router as users_router
-from app.core.config import get_settings
+from app.core.config import Settings, get_settings
 from app.core.errors import register_exception_handlers
+from app.core.security import hash_password
+from app.repositories.factory import get_portfolio_repository_from_settings
+from app.repositories.portfolio_repository import PortfolioRepository
 
 
-def create_app() -> FastAPI:
-    settings = get_settings()
+def _bootstrap_initial_user(
+    settings: Settings,
+    repository_factory: Callable[[Settings], PortfolioRepository],
+) -> None:
+    if not settings.db_enabled or settings.bootstrap_user_username is None or settings.bootstrap_user_password is None:
+        return
+
+    repository = repository_factory(settings)
+    try:
+        if repository.list_users():
+            return
+        repository.create_user(
+            settings.bootstrap_user_username,
+            email=settings.bootstrap_user_email,
+            password_hash=hash_password(settings.bootstrap_user_password),
+            permission="admin",
+        )
+    finally:
+        if callable(getattr(type(repository), "close", None)):
+            repository.close()
+
+
+def create_app(
+    *,
+    settings_factory: Callable[[], Settings] = get_settings,
+    repository_factory: Callable[[Settings], PortfolioRepository] = get_portfolio_repository_from_settings,
+) -> FastAPI:
+    settings = settings_factory()
+
+    @asynccontextmanager
+    async def lifespan(_: FastAPI):
+        _bootstrap_initial_user(settings, repository_factory)
+        yield
+
     app = FastAPI(
         title=settings.app_name,
         version=settings.app_version,
         docs_url="/docs",
         redoc_url="/redoc",
+        lifespan=lifespan,
     )
 
     app.add_middleware(
@@ -29,6 +69,7 @@ def create_app() -> FastAPI:
     )
 
     app.include_router(health_router)
+    app.include_router(auth_router)
     app.include_router(portfolio_router)
     app.include_router(strategy_sets_router)
     app.include_router(users_router)

app/repositories/portfolio_repository.py

@@ -2,9 +2,10 @@
 
 from __future__ import annotations
 
+from datetime import datetime
 from typing import Protocol
 
-from app.domain.models import LedgerEntry, Portfolio, StrategySet, User
+from app.domain.models import AuthToken, LedgerEntry, Portfolio, StrategySet, TokenPrincipal, User
 
 
 class PortfolioRepository(Protocol):
@@ -12,14 +13,53 @@ class PortfolioRepository(Protocol):
 
     def get_user(self, user_id: str) -> User: ...
 
+    def get_user_by_username(self, username: str) -> User | None: ...
+
     def list_users(self) -> list[User]: ...
 
-    def create_user(self, username: str, *, email: str | None = None) -> User: ...
+    def create_user(
+        self,
+        username: str,
+        *,
+        email: str | None = None,
+        password_hash: str | None = None,
+        permission: str = "read",
+        is_active: bool = True,
+    ) -> User: ...
 
-    def update_user(self, user_id: str, *, username: str | None = None, email: str | None = None) -> User: ...
+    def update_user(
+        self,
+        user_id: str,
+        *,
+        username: str | None = None,
+        email: str | None = None,
+        password_hash: str | None = None,
+        permission: str | None = None,
+        is_active: bool | None = None,
+    ) -> User: ...
 
     def delete_user(self, user_id: str) -> None: ...
 
+    def update_user_last_login(self, user_id: str) -> None: ...
+
+    def create_auth_token(
+        self,
+        user_id: str,
+        *,
+        name: str,
+        token_hash: str,
+        token_prefix: str,
+        permission: str,
+        token_type: str,
+        expires_at: datetime | None = None,
+    ) -> AuthToken: ...
+
+    def list_auth_tokens(self, user_id: str) -> list[AuthToken]: ...
+
+    def revoke_auth_token(self, user_id: str, token_id: str) -> None: ...
+
+    def get_token_principal(self, token_hash: str) -> TokenPrincipal | None: ...
+
     def get(self, portfolio_id: str) -> Portfolio: ...
 
     def get_or_create(

app/repositories/postgres.py

@@ -12,18 +12,37 @@ from typing import Any
 import psycopg
 from psycopg import sql
 
-from app.domain.models import LedgerEntry, Portfolio, StrategySet, User
+from app.domain.models import AuthToken, LedgerEntry, Portfolio, StrategySet, TokenPrincipal, User
 
 _SELECT_USER = """
     SELECT
         id,
         username,
         email,
+        permission,
+        is_active,
+        password_hash,
         created_at,
-        updated_at
+        updated_at,
+        last_login_at
     FROM users
 """
 
+_SELECT_AUTH_TOKEN = """
+    SELECT
+        id,
+        user_id,
+        name,
+        token_prefix,
+        permission,
+        token_type,
+        expires_at,
+        last_used_at,
+        revoked_at,
+        created_at
+    FROM auth_tokens
+"""
+
 _SELECT_PORTFOLIO = """
     SELECT
         portfolio_id,
@@ -94,11 +113,44 @@ class PostgresPortfolioRepository:
                     id TEXT PRIMARY KEY,
                     username TEXT NOT NULL UNIQUE,
                     email TEXT UNIQUE,
+                    permission TEXT NOT NULL DEFAULT 'read',
+                    is_active BOOLEAN NOT NULL DEFAULT TRUE,
+                    password_hash TEXT,
                     created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-                    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+                    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                    last_login_at TIMESTAMPTZ
                 )
                 """
             )
+            cur.execute(
+                """
+                CREATE TABLE IF NOT EXISTS auth_tokens (
+                    id TEXT PRIMARY KEY,
+                    user_id TEXT NOT NULL,
+                    name TEXT NOT NULL,
+                    token_prefix TEXT NOT NULL,
+                    token_hash TEXT NOT NULL UNIQUE,
+                    permission TEXT NOT NULL,
+                    token_type TEXT NOT NULL,
+                    expires_at TIMESTAMPTZ,
+                    last_used_at TIMESTAMPTZ,
+                    revoked_at TIMESTAMPTZ,
+                    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+                )
+                """
+            )
+            cur.execute(
+                """
+                CREATE INDEX IF NOT EXISTS idx_auth_tokens_user_created
+                ON auth_tokens (user_id, created_at DESC)
+                """
+            )
+            cur.execute(
+                """
+                CREATE INDEX IF NOT EXISTS idx_auth_tokens_hash_active
+                ON auth_tokens (token_hash)
+                """
+            )
             cur.execute(
                 """
                 CREATE TABLE IF NOT EXISTS strategy_sets (
@@ -178,8 +230,29 @@ class PostgresPortfolioRepository:
             id=row[0],
             username=row[1],
             email=row[2],
-            created_at=row[3] if len(row) > 3 else None,
-            updated_at=row[4] if len(row) > 4 else None,
+            permission=row[3] if len(row) > 3 else "read",
+            is_active=bool(row[4]) if len(row) > 4 else True,
+            password_hash=row[5] if len(row) > 5 else None,
+            created_at=row[6] if len(row) > 6 else None,
+            updated_at=row[7] if len(row) > 7 else None,
+            last_login_at=row[8] if len(row) > 8 else None,
+        )
+
+    @staticmethod
+    def _row_to_auth_token(row: Any) -> AuthToken:
+        if row is None:
+            raise ValueError("토큰을 찾을 수 없습니다")
+        return AuthToken(
+            id=row[0],
+            user_id=row[1],
+            name=row[2],
+            token_prefix=row[3],
+            permission=row[4],
+            token_type=row[5],
+            expires_at=row[6] if len(row) > 6 else None,
+            last_used_at=row[7] if len(row) > 7 else None,
+            revoked_at=row[8] if len(row) > 8 else None,
+            created_at=row[9] if len(row) > 9 else None,
         )
 
     @staticmethod
@@ -260,6 +333,15 @@ class PostgresPortfolioRepository:
             row = cur.fetchone()
         return self._row_to_user(row)
 
+    def get_user_by_username(self, username: str) -> User | None:
+        self.ensure_schema()
+        with self._connect().cursor() as cur:
+            cur.execute(_SELECT_USER + "WHERE username = %s", (username,))
+            row = cur.fetchone()
+        if row is None:
+            return None
+        return self._row_to_user(row)
+
     def list_users(self) -> list[User]:
         self.ensure_schema()
         with self._connect().cursor() as cur:
@@ -267,23 +349,40 @@ class PostgresPortfolioRepository:
             rows = cur.fetchall()
         return [self._row_to_user(row) for row in rows]
 
-    def create_user(self, username: str, *, email: str | None = None) -> User:
+    def create_user(
+        self,
+        username: str,
+        *,
+        email: str | None = None,
+        password_hash: str | None = None,
+        permission: str = "read",
+        is_active: bool = True,
+    ) -> User:
         self.ensure_schema()
         with self._connect().cursor() as cur:
             self._ensure_user_uniqueness(cur, username=username, email=email)
             user_id = str(uuid.uuid4())
             cur.execute(
                 """
-                INSERT INTO users (id, username, email)
-                VALUES (%s, %s, %s)
-                RETURNING id, username, email, created_at, updated_at
+                INSERT INTO users (id, username, email, permission, is_active, password_hash)
+                VALUES (%s, %s, %s, %s, %s, %s)
+                RETURNING id, username, email, permission, is_active, password_hash, created_at, updated_at, last_login_at
                 """,
-                (user_id, username, email),
+                (user_id, username, email, permission, is_active, password_hash),
             )
             row = cur.fetchone()
         return self._row_to_user(row)
 
-    def update_user(self, user_id: str, *, username: str | None = None, email: str | None = None) -> User:
+    def update_user(
+        self,
+        user_id: str,
+        *,
+        username: str | None = None,
+        email: str | None = None,
+        password_hash: str | None = None,
+        permission: str | None = None,
+        is_active: bool | None = None,
+    ) -> User:
         self.ensure_schema()
         assignments: list[str] = []
         params: list[object] = []
@@ -301,6 +400,15 @@ class PostgresPortfolioRepository:
             if email is not None:
                 assignments.append("email = %s")
                 params.append(email)
+            if password_hash is not None:
+                assignments.append("password_hash = %s")
+                params.append(password_hash)
+            if permission is not None:
+                assignments.append("permission = %s")
+                params.append(permission)
+            if is_active is not None:
+                assignments.append("is_active = %s")
+                params.append(is_active)
 
             if not assignments:
                 return self._row_to_user(existing_row)
@@ -311,7 +419,7 @@ class PostgresPortfolioRepository:
                 UPDATE users
                 SET {', '.join(assignments)}
                 WHERE id = %s
-                RETURNING id, username, email, created_at, updated_at
+                RETURNING id, username, email, permission, is_active, password_hash, created_at, updated_at, last_login_at
                 """,
                 (*params, user_id),
             )
@@ -324,8 +432,85 @@ class PostgresPortfolioRepository:
             cur.execute("SELECT 1 FROM users WHERE id = %s", (user_id,))
             if cur.fetchone() is None:
                 raise ValueError("사용자를 찾을 수 없습니다")
+            cur.execute("DELETE FROM auth_tokens WHERE user_id = %s", (user_id,))
             cur.execute("DELETE FROM users WHERE id = %s", (user_id,))
 
+    def update_user_last_login(self, user_id: str) -> None:
+        self.ensure_schema()
+        with self._connect().cursor() as cur:
+            cur.execute(
+                "UPDATE users SET last_login_at = NOW(), updated_at = NOW() WHERE id = %s",
+                (user_id,),
+            )
+
+    def create_auth_token(
+        self,
+        user_id: str,
+        *,
+        name: str,
+        token_hash: str,
+        token_prefix: str,
+        permission: str,
+        token_type: str,
+        expires_at: datetime | None = None,
+    ) -> AuthToken:
+        self.ensure_schema()
+        with self._connect().cursor() as cur:
+            cur.execute("SELECT 1 FROM users WHERE id = %s", (user_id,))
+            if cur.fetchone() is None:
+                raise ValueError("사용자를 찾을 수 없습니다")
+            token_id = str(uuid.uuid4())
+            cur.execute(
+                """
+                INSERT INTO auth_tokens (id, user_id, name, token_prefix, token_hash, permission, token_type, expires_at)
+                VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
+                RETURNING id, user_id, name, token_prefix, permission, token_type, expires_at, last_used_at, revoked_at, created_at
+                """,
+                (token_id, user_id, name, token_prefix, token_hash, permission, token_type, expires_at),
+            )
+            row = cur.fetchone()
+        return self._row_to_auth_token(row)
+
+    def list_auth_tokens(self, user_id: str) -> list[AuthToken]:
+        self.ensure_schema()
+        with self._connect().cursor() as cur:
+            cur.execute(
+                _SELECT_AUTH_TOKEN + "WHERE user_id = %s ORDER BY created_at DESC, id ASC",
+                (user_id,),
+            )
+            rows = cur.fetchall()
+        return [self._row_to_auth_token(row) for row in rows]
+
+    def revoke_auth_token(self, user_id: str, token_id: str) -> None:
+        self.ensure_schema()
+        with self._connect().cursor() as cur:
+            cur.execute(
+                "UPDATE auth_tokens SET revoked_at = NOW() WHERE id = %s AND user_id = %s RETURNING id",
+                (token_id, user_id),
+            )
+            row = cur.fetchone()
+            if row is None:
+                raise ValueError("토큰을 찾을 수 없습니다")
+
+    def get_token_principal(self, token_hash: str) -> TokenPrincipal | None:
+        self.ensure_schema()
+        with self._connect().cursor() as cur:
+            cur.execute(
+                """
+                SELECT id, user_id, permission, token_type
+                FROM auth_tokens
+                WHERE token_hash = %s
+                  AND revoked_at IS NULL
+                  AND (expires_at IS NULL OR expires_at > NOW())
+                """,
+                (token_hash,),
+            )
+            row = cur.fetchone()
+            if row is None:
+                return None
+            cur.execute("UPDATE auth_tokens SET last_used_at = NOW() WHERE id = %s", (row[0],))
+        return TokenPrincipal(token_id=row[0], user_id=row[1], permission=row[2], token_type=row[3])
+
     def get(self, portfolio_id: str) -> Portfolio:
         self.ensure_schema()
         with self._connect().cursor() as cur:

app/schemas/auth.py

@@ -0,0 +1,64 @@
+"""Authentication request and response schemas."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+from app.schemas.user import UserResponse
+
+
+class LoginRequest(BaseModel):
+    username: str = Field(min_length=1)
+    password: str = Field(min_length=1)
+
+    @field_validator("username")
+    @classmethod
+    def normalize_username(cls, value: str) -> str:
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError("username은 비어 있을 수 없습니다")
+        return normalized
+
+
+class TokenResponse(BaseModel):
+    access_token: str
+    token_type: Literal["bearer"] = "bearer"
+    expires_at: datetime | None = None
+    permission: Literal["read", "trade-write", "admin"]
+    user: UserResponse
+
+
+class CreateClientTokenRequest(BaseModel):
+    name: str = Field(min_length=1)
+    permission: Literal["read", "trade-write", "admin"] | None = None
+    expires_in_days: int | None = Field(default=None, ge=1, le=3650)
+
+    @field_validator("name")
+    @classmethod
+    def normalize_name(cls, value: str) -> str:
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError("name은 비어 있을 수 없습니다")
+        return normalized
+
+
+class AuthTokenResponse(BaseModel):
+    id: str
+    user_id: str
+    name: str
+    token_prefix: str
+    permission: Literal["read", "trade-write", "admin"]
+    token_type: Literal["session", "client"]
+    expires_at: datetime | None = None
+    last_used_at: datetime | None = None
+    revoked_at: datetime | None = None
+    created_at: datetime | None = None
+
+
+class IssuedClientTokenResponse(BaseModel):
+    token: str
+    token_type: Literal["bearer"] = "bearer"
+    auth_token: AuthTokenResponse

app/schemas/user.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from datetime import datetime
+from typing import Literal
 
 from pydantic import BaseModel, Field, field_validator
 
@@ -11,13 +12,19 @@ class UserResponse(BaseModel):
     id: str
     username: str
     email: str | None = None
+    permission: Literal["read", "trade-write", "admin"] = "read"
+    is_active: bool = True
     created_at: datetime | None = None
     updated_at: datetime | None = None
+    last_login_at: datetime | None = None
 
 
 class CreateUserRequest(BaseModel):
     username: str = Field(min_length=1)
     email: str | None = None
+    password: str = Field(min_length=8)
+    permission: Literal["read", "trade-write", "admin"] = "read"
+    is_active: bool = True
 
     @field_validator("username")
     @classmethod
@@ -39,6 +46,9 @@ class CreateUserRequest(BaseModel):
 class UpdateUserRequest(BaseModel):
     username: str | None = Field(default=None, min_length=1)
     email: str | None = None
+    password: str | None = Field(default=None, min_length=8)
+    permission: Literal["read", "trade-write", "admin"] | None = None
+    is_active: bool | None = None
 
     @field_validator("username")
     @classmethod

app/services/auth_service.py

@@ -0,0 +1,102 @@
+"""Authentication and token issuance service."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+from fastapi import Depends
+
+from app.core.auth import AuthContext, Permission, _has_permission
+from app.core.config import Settings, get_settings
+from app.core.security import generate_token, hash_token, token_prefix, verify_password
+from app.domain.models import AuthToken, User
+from app.repositories.factory import get_portfolio_repository_from_settings
+from app.repositories.portfolio_repository import PortfolioRepository
+from app.schemas.auth import CreateClientTokenRequest, LoginRequest
+
+
+@dataclass
+class LoginResult:
+    token: str
+    auth_token: AuthToken
+    user: User
+
+
+@dataclass
+class IssuedClientToken:
+    token: str
+    auth_token: AuthToken
+
+
+def get_auth_service_repository(settings: Settings = Depends(get_settings)) -> PortfolioRepository:
+    return get_portfolio_repository_from_settings(settings)
+
+
+class AuthService:
+    def __init__(self, repository: PortfolioRepository, settings: Settings) -> None:
+        self._repository = repository
+        self._settings = settings
+
+    def login(self, payload: LoginRequest) -> LoginResult:
+        user = self._repository.get_user_by_username(payload.username)
+        if user is None or not user.is_active or not verify_password(payload.password, user.password_hash):
+            raise ValueError("잘못된 사용자명 또는 비밀번호입니다")
+
+        raw_token = generate_token()
+        expires_at = datetime.now(timezone.utc) + timedelta(hours=self._settings.session_token_ttl_hours)
+        auth_token = self._repository.create_auth_token(
+            user.id,
+            name="session",
+            token_hash=hash_token(raw_token),
+            token_prefix=token_prefix(raw_token),
+            permission=user.permission,
+            token_type="session",
+            expires_at=expires_at,
+        )
+        self._repository.update_user_last_login(user.id)
+        refreshed_user = self._repository.get_user(user.id)
+        return LoginResult(token=raw_token, auth_token=auth_token, user=refreshed_user)
+
+    def issue_client_token(self, auth_context: AuthContext, payload: CreateClientTokenRequest) -> IssuedClientToken:
+        if auth_context.user_id is None:
+            raise ValueError("DB 사용자 컨텍스트에서만 클라이언트 토큰을 발급할 수 있습니다")
+
+        requested = Permission(payload.permission or auth_context.permission.value)
+        if not _has_permission(auth_context.permission, requested):
+            raise ValueError("요청한 토큰 권한이 현재 권한을 초과합니다")
+
+        raw_token = generate_token()
+        expires_at = None
+        if payload.expires_in_days is not None:
+            expires_at = datetime.now(timezone.utc) + timedelta(days=payload.expires_in_days)
+        else:
+            expires_at = datetime.now(timezone.utc) + timedelta(days=self._settings.client_token_default_ttl_days)
+
+        auth_token = self._repository.create_auth_token(
+            auth_context.user_id,
+            name=payload.name,
+            token_hash=hash_token(raw_token),
+            token_prefix=token_prefix(raw_token),
+            permission=requested.value,
+            token_type="client",
+            expires_at=expires_at,
+        )
+        return IssuedClientToken(token=raw_token, auth_token=auth_token)
+
+    def list_tokens(self, auth_context: AuthContext) -> list[AuthToken]:
+        if auth_context.user_id is None:
+            raise ValueError("DB 사용자 컨텍스트에서만 토큰 목록을 조회할 수 있습니다")
+        return self._repository.list_auth_tokens(auth_context.user_id)
+
+    def revoke_token(self, auth_context: AuthContext, token_id: str) -> None:
+        if auth_context.user_id is None:
+            raise ValueError("DB 사용자 컨텍스트에서만 토큰을 폐기할 수 있습니다")
+        self._repository.revoke_auth_token(auth_context.user_id, token_id)
+
+
+def get_auth_service(
+    settings: Settings = Depends(get_settings),
+    repository: PortfolioRepository = Depends(get_auth_service_repository),
+) -> AuthService:
+    return AuthService(repository, settings)

app/services/user_service.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from fastapi import Depends
 
 from app.core.config import Settings, get_settings
+from app.core.security import hash_password
 from app.domain.models import User
 from app.repositories.factory import get_portfolio_repository_from_settings
 from app.repositories.portfolio_repository import PortfolioRepository
@@ -26,13 +27,22 @@ class UserService:
         return self._repository.get_user(user_id)
 
     def create(self, payload: CreateUserRequest) -> User:
-        return self._repository.create_user(payload.username, email=payload.email)
+        return self._repository.create_user(
+            payload.username,
+            email=payload.email,
+            password_hash=hash_password(payload.password),
+            permission=payload.permission,
+            is_active=payload.is_active,
+        )
 
     def update(self, user_id: str, payload: UpdateUserRequest) -> User:
         return self._repository.update_user(
             user_id,
             username=payload.username,
             email=payload.email,
+            password_hash=hash_password(payload.password) if payload.password is not None else None,
+            permission=payload.permission,
+            is_active=payload.is_active,
         )
 
     def delete(self, user_id: str) -> None: