"""Admin API: users, roles and the audit log (SRS FR-RBAC-05/09).""" from __future__ import annotations import uuid from datetime import datetime from typing import Literal from fastapi import APIRouter, Depends, Query, Request, Response from pydantic import BaseModel, Field from sqlalchemy import select from app.auth.permissions import Perm, Principal, Role from app.auth.web import request_meta, require from app.core.errors import InvalidRequestError from app.db.models import AuditEvent, User router = APIRouter(prefix="/v1", tags=["admin"]) class UserInfo(BaseModel): id: uuid.UUID email: str display_name: str | None role: str status: str is_service_account: bool created_at: datetime last_seen_at: datetime | None @classmethod def of(cls, u: User) -> UserInfo: return cls(id=u.id, email=u.email, display_name=u.display_name, role=u.role, status=u.status, is_service_account=u.is_service_account, created_at=u.created_at, last_seen_at=u.last_seen_at) class UserInvite(BaseModel): email: str = Field(max_length=320) role: Role = Role.LEARNER display_name: str | None = Field(default=None, max_length=200) class UserUpdate(BaseModel): role: Role | None = None status: Literal["active", "suspended"] | None = None reason: str | None = Field(default=None, max_length=500) class AuditEntry(BaseModel): id: int ts: datetime actor_id: uuid.UUID | None action: str target_type: str | None target_id: str | None reason: str | None details: dict request_id: str | None ip: str | None @router.get("/users", response_model=list[UserInfo]) def list_users(request: Request, _: Principal = Depends(require(Perm.USERS_MANAGE))) -> list[UserInfo]: return [UserInfo.of(u) for u in request.app.state.users.list()] @router.post("/users", response_model=UserInfo, status_code=201) def invite_user(body: UserInvite, request: Request, principal: Principal = Depends(require(Perm.USERS_MANAGE))) -> UserInfo: """Invite a user by email. They activate the account by signing in with that address.""" user = request.app.state.users.invite(principal, body.email, body.role, body.display_name, request_meta(request)) return UserInfo.of(user) @router.patch("/users/{user_id}", response_model=UserInfo) def update_user(user_id: uuid.UUID, body: UserUpdate, request: Request, principal: Principal = Depends(require(Perm.USERS_MANAGE))) -> UserInfo: if body.role is None and body.status is None: raise InvalidRequestError("nothing to change: give a role and/or a status") users = request.app.state.users meta = request_meta(request) user = None if body.role is not None: user = users.change_role(principal, user_id, body.role, meta) if body.status is not None: user = users.set_status(principal, user_id, body.status, body.reason, meta) return UserInfo.of(user) @router.delete("/users/{user_id}", status_code=204) def delete_user(user_id: uuid.UUID, request: Request, reason: str | None = Query(None, max_length=500), principal: Principal = Depends(require(Perm.USERS_MANAGE))) -> Response: """Delete an account: sign-in methods, sessions, API tokens and conversations are removed. Books the user uploaded pass to the deleting Admin. You cannot delete yourself or the last active Admin.""" request.app.state.users.delete(principal, user_id, reason, request_meta(request)) return Response(status_code=204) @router.get("/audit", response_model=list[AuditEntry]) def audit_log(request: Request, limit: int = Query(100, ge=1, le=1000), action: str | None = None, _: Principal = Depends(require(Perm.AUDIT_READ))) -> list[AuditEntry]: """Most recent first. Filter by action prefix, e.g. `user.` or `auth.sign_in`.""" with request.app.state.db.session() as s: q = select(AuditEvent).order_by(AuditEvent.id.desc()).limit(limit) if action: q = q.where(AuditEvent.action.startswith(action)) return [AuditEntry.model_validate(e, from_attributes=True) for e in s.scalars(q)]