api(auth): add auth endpoints (setup, login, logout, status), tests, and dependency token decoding; update docs

src/server/api/auth.py

@@ -0,0 +1,62 @@
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.security import HTTPAuthorizationCredentials
+
+from src.server.models.auth import AuthStatus, LoginRequest, LoginResponse, SetupRequest
+from src.server.services.auth_service import AuthError, LockedOutError, auth_service
+from src.server.utils.dependencies import optional_auth, security
+
+router = APIRouter(prefix="/api/auth", tags=["auth"])
+
+
+@router.post("/setup", status_code=status.HTTP_201_CREATED)
+def setup_auth(req: SetupRequest):
+    """Initial setup endpoint to configure the master password."""
+    if auth_service.is_configured():
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Master password already configured",
+        )
+
+    try:
+        auth_service.setup_master_password(req.master_password)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    return {"status": "ok"}
+
+
+@router.post("/login", response_model=LoginResponse)
+def login(req: LoginRequest):
+    """Validate master password and return JWT token."""
+    # Use a simple identifier for failed attempts; prefer IP in a real app
+    identifier = "global"
+
+    try:
+        valid = auth_service.validate_master_password(req.password, identifier=identifier)
+    except AuthError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except LockedOutError as e:
+        raise HTTPException(status_code=429, detail=str(e))
+
+    if not valid:
+        raise HTTPException(status_code=401, detail="Invalid credentials")
+
+    token = auth_service.create_access_token(subject="master", remember=bool(req.remember))
+    return token
+
+
+@router.post("/logout")
+def logout(credentials: HTTPAuthorizationCredentials = Depends(security)):
+    """Logout by revoking token (no-op for stateless JWT)."""
+    token = credentials.credentials
+    # Placeholder; auth_service.revoke_token can be expanded to persist revocations
+    auth_service.revoke_token(token)
+    return {"status": "ok"}
+
+
+@router.get("/status", response_model=AuthStatus)
+def status(auth: Optional[dict] = Depends(optional_auth)):
+    """Return whether master password is configured and if caller is authenticated."""
+    return AuthStatus(configured=auth_service.is_configured(), authenticated=bool(auth))