qodalis-cli-server-plugin-users 1.0.0b6__py3-none-any.whl

qodalis_cli_users/controllers/users_controller.py

@@ -0,0 +1,183 @@
+"""Users controller — ``/users`` (CRUD, permissions, password)."""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from fastapi import APIRouter, Depends, Query, Request, Response
+
+from ..errors import bad_request, error_response, forbidden, not_found
+from ..models import (
+    CreateUserRequest,
+    PasswordChangeRequest,
+    UpdateUserRequest,
+    User,
+    VerifyPasswordRequest,
+)
+from ..permissions import USERS_CREATE, USERS_DELETE, USERS_READ, USERS_UPDATE
+from ..services.auth_service import AuthContext, AuthService
+from ..services.users_service import UsersService
+from ._routing import collection, new_router
+
+MANAGED_BY_HOST = "Authentication is managed by the host application"
+
+
+def create_users_router(
+    auth_service: AuthService,
+    users_service: UsersService,
+    get_auth: Callable,
+    require_permission: Callable[[str], Callable],
+    get_auth_pending: Callable | None = None,
+) -> APIRouter:
+    get_auth_pending = get_auth_pending or get_auth
+    router = new_router("/users", "users")
+    user_store = auth_service.user_store
+    external = auth_service.external_auth
+
+    async def load_target(id_or_name: str, ctx: AuthContext, permission: str, *, allow_self: bool) -> User:
+        """Resolve the target user, enforcing ``permission`` (or self).
+
+        Callers lacking the permission get 403 rather than 404 so user
+        existence is not leaked to them.
+        """
+        target = await user_store.get_user(id_or_name)
+        allowed = ctx.can(permission) or (allow_self and ctx.is_self(target))
+        if not allowed:
+            raise forbidden(f"missing permission: {permission}")
+        if target is None:
+            raise not_found(f"user not found: {id_or_name}")
+        return target
+
+    @collection(router, "GET")
+    async def list_users(
+        query: str | None = None,
+        skip: int = Query(default=0, ge=0),
+        take: int | None = Query(default=None, ge=0),
+        ctx: AuthContext = Depends(require_permission(USERS_READ)),
+    ):
+        users = await users_service.list_users(query, skip, take)
+        return [u.to_dict() for u in users]
+
+    @collection(router, "POST", status_code=201)
+    async def create_user(
+        body: CreateUserRequest,
+        ctx: AuthContext = Depends(require_permission(USERS_CREATE)),
+    ):
+        user = await users_service.create_user(
+            ctx,
+            name=body.name,
+            email=body.email,
+            groups=body.groups,
+            password=body.password,
+            disabled=body.disabled,
+            home_dir=body.homeDir,
+            data=body.data,
+        )
+        return user.to_dict()
+
+    @router.get("/{id_or_name}")
+    async def get_user(id_or_name: str, ctx: AuthContext = Depends(get_auth)):
+        target = await load_target(id_or_name, ctx, USERS_READ, allow_self=True)
+        return target.to_dict()
+
+    @router.get("/{id_or_name}/permissions")
+    async def get_user_permissions(id_or_name: str, ctx: AuthContext = Depends(get_auth)):
+        target = await load_target(id_or_name, ctx, USERS_READ, allow_self=True)
+        groups = list(target.groups or [])
+        return {
+            "userId": target.id,
+            "groups": groups,
+            "permissions": await auth_service.effective_permissions(groups),
+        }
+
+    @router.put("/{id_or_name}")
+    async def update_user(
+        id_or_name: str,
+        body: UpdateUserRequest,
+        ctx: AuthContext = Depends(get_auth),
+    ):
+        target = await load_target(id_or_name, ctx, USERS_UPDATE, allow_self=True)
+        if not ctx.can(USERS_UPDATE):
+            # Self-service: only email and data may change.
+            restricted = [
+                f for f, v in (
+                    ("name", body.name),
+                    ("groups", body.groups),
+                    ("disabled", body.disabled),
+                    ("homeDir", body.homeDir),
+                ) if v is not None
+            ]
+            if restricted:
+                raise forbidden(f"missing permission: {USERS_UPDATE}")
+        user = await users_service.update_user(
+            ctx,
+            target,
+            name=body.name,
+            email=body.email,
+            groups=body.groups,
+            disabled=body.disabled,
+            home_dir=body.homeDir,
+            data=body.data,
+        )
+        return user.to_dict()
+
+    @router.delete("/{id_or_name}", status_code=204)
+    async def delete_user(
+        id_or_name: str,
+        ctx: AuthContext = Depends(require_permission(USERS_DELETE)),
+    ):
+        target = await load_target(id_or_name, ctx, USERS_DELETE, allow_self=False)
+        await users_service.delete_user(ctx, target)
+        return Response(status_code=204)
+
+    if external:
+        @router.put("/{id_or_name}/password")
+        async def change_password_external(id_or_name: str):
+            return error_response(501, MANAGED_BY_HOST)
+
+        @router.post("/{id_or_name}/verify-password")
+        async def verify_password_external(id_or_name: str):
+            return error_response(501, MANAGED_BY_HOST)
+
+        return router
+
+    @router.put("/{id_or_name}/password", status_code=204)
+    async def change_password(
+        id_or_name: str,
+        body: PasswordChangeRequest,
+        request: Request,
+        ctx: AuthContext = Depends(get_auth_pending),
+    ):
+        target = await user_store.get_user(id_or_name)
+        is_self = ctx.is_self(target)
+        # While a password change is pending only the own password may change.
+        if not is_self:
+            auth_service.ensure_password_changed(ctx)
+        target = await load_target(id_or_name, ctx, USERS_UPDATE, allow_self=True)
+        password = body.password if body.password is not None else body.newPassword
+        if password is None:
+            raise bad_request("password is required")
+        if is_self:
+            auth_service.check_rate_limit(request)
+        if is_self and (not ctx.can(USERS_UPDATE) or ctx.must_change_password):
+            if not body.currentPassword:
+                raise bad_request("currentPassword is required")
+            if not await auth_service.check_password_attempt(ctx, target, body.currentPassword):
+                raise forbidden("current password is incorrect")
+        await users_service.change_password(ctx, target, password, temporary=body.temporary)
+        return Response(status_code=204)
+
+    @router.post("/{id_or_name}/verify-password")
+    async def verify_password(
+        id_or_name: str,
+        body: VerifyPasswordRequest,
+        request: Request,
+        ctx: AuthContext = Depends(get_auth),
+    ):
+        target = await load_target(id_or_name, ctx, USERS_UPDATE, allow_self=True)
+        await auth_service.ensure_covers_user(ctx, target)
+        auth_service.check_rate_limit(request)
+        valid = await auth_service.check_password_attempt(ctx, target, body.password)
+        return {"valid": valid}
+
+    return router

qodalis_cli_users/errors.py

@@ -0,0 +1,118 @@
+"""Error handling for the users routes.
+
+Every error produced by the users routes — including FastAPI's request
+validation errors (422 by default) and ``HTTPException``s raised by
+dependencies — is returned as ``{"error": "<message>"}``; validation errors
+become 400.  This is scoped to the users routers via a custom route class, so
+other routers of the host app keep FastAPI's default behaviour.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Coroutine
+
+from fastapi import HTTPException, Request, Response
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from fastapi.routing import APIRoute
+
+BODY_MAX_BYTES = 1024 * 1024
+
+
+class UsersApiError(HTTPException):
+    """An error with an HTTP status, rendered as ``{"error": message}`` on the
+    users routes (and by the server-protection middleware).  Being an
+    ``HTTPException`` it also works in host-app routes using the exported
+    guards."""
+
+    def __init__(self, status_code: int, message: str) -> None:
+        super().__init__(status_code=status_code, detail=message)
+        self.message = message
+
+
+def bad_request(message: str) -> UsersApiError:
+    return UsersApiError(400, message)
+
+
+def unauthorized(message: str = "unauthorized") -> UsersApiError:
+    return UsersApiError(401, message)
+
+
+def forbidden(message: str = "forbidden") -> UsersApiError:
+    return UsersApiError(403, message)
+
+
+def not_found(message: str) -> UsersApiError:
+    return UsersApiError(404, message)
+
+
+def conflict(message: str) -> UsersApiError:
+    return UsersApiError(409, message)
+
+
+def error_response(status_code: int, message: str) -> JSONResponse:
+    return JSONResponse(status_code=status_code, content={"error": message})
+
+
+def _validation_message(exc: RequestValidationError) -> str:
+    errors = exc.errors()
+    if not errors:
+        return "invalid request"
+    first = errors[0]
+    loc = [str(p) for p in first.get("loc", ()) if p not in ("body", "query", "path")]
+    field = ".".join(loc)
+    err_type = first.get("type", "")
+    if err_type == "missing":
+        return f"{field} is required" if field else "request body is required"
+    if err_type in ("json_invalid", "model_attributes_type") or not field:
+        return "invalid request body"
+    return f"invalid {field}: {first.get('msg', 'invalid value')}"
+
+
+async def _read_body_capped(request: Request) -> bool:
+    """Read the body, stopping as soon as it exceeds ``BODY_MAX_BYTES``
+    (chunked bodies have no Content-Length).  ``False`` when too large;
+    otherwise the body is cached on the request for the handler."""
+    chunks: list[bytes] = []
+    size = 0
+    async for chunk in request.stream():
+        size += len(chunk)
+        if size > BODY_MAX_BYTES:
+            return False
+        chunks.append(chunk)
+    request._body = b"".join(chunks)
+    return True
+
+
+class UsersApiRoute(APIRoute):
+    """Route class converting validation/HTTP errors to ``{error}`` bodies."""
+
+    def get_route_handler(self) -> Callable[[Request], Coroutine[Any, Any, Response]]:
+        original = super().get_route_handler()
+
+        async def handler(request: Request) -> Response:
+            length = request.headers.get("content-length")
+            try:
+                too_large = length is not None and int(length) > BODY_MAX_BYTES
+            except ValueError:
+                too_large = True
+            if too_large or (
+                request.method in ("POST", "PUT", "PATCH")
+                and not await _read_body_capped(request)
+            ):
+                return error_response(400, "request body too large")
+            try:
+                return await original(request)
+            except UsersApiError as exc:
+                return error_response(exc.status_code, exc.message)
+            except RequestValidationError as exc:
+                return error_response(400, _validation_message(exc))
+            except HTTPException as exc:
+                detail = exc.detail if isinstance(exc.detail, str) else str(exc.detail)
+                return JSONResponse(
+                    status_code=exc.status_code,
+                    content={"error": detail},
+                    headers=getattr(exc, "headers", None),
+                )
+
+        return handler

qodalis_cli_users/middleware/__init__.py

@@ -0,0 +1,5 @@
+"""Users plugin middleware."""
+
+from .auth_middleware import authenticate_request, create_auth_dependencies
+
+__all__ = ["authenticate_request", "create_auth_dependencies"]

qodalis_cli_users/middleware/auth_middleware.py

@@ -0,0 +1,77 @@
+"""FastAPI dependencies for authenticating users-plugin (and host) requests.
+
+``get_auth`` resolves the caller (bearer token, or the external auth adapter)
+to an :class:`AuthContext` holding the **live** user and its effective
+permissions, and enforces CSRF (B9) and the ``mustChangePassword`` gate (B4).
+``get_auth_pending`` is the same without the password-change gate (for the
+few endpoints allowed while a password change is pending).
+"""
+
+from __future__ import annotations
+
+from typing import Awaitable, Callable
+
+from fastapi import Depends, Request
+
+from .._http import SAFE_METHODS, bearer_token, get_scope_auth, has_bearer, origin_allowed
+from ..errors import forbidden, unauthorized
+from ..services.auth_service import AuthContext, AuthService
+
+GetAuth = Callable[[Request], Awaitable[AuthContext]]
+
+ORIGIN_NOT_ALLOWED = "origin not allowed"
+
+
+async def authenticate_request(auth_service: AuthService, request: Request) -> AuthContext:
+    """Authenticate an HTTP request (no password-change gate)."""
+    if auth_service.external_auth:
+        # Ambient (adapter/cookie) credentials: state-changing requests
+        # without a bearer token must come from an allowed Origin (CSRF);
+        # same-origin requests (e.g. the bundled dashboard) always pass.
+        if request.method.upper() not in SAFE_METHODS and not has_bearer(request.headers):
+            if not origin_allowed(
+                request.headers.get("origin"),
+                auth_service.options.allowed_origins,
+                request.scope,
+                auth_service.options.trust_proxy,
+            ):
+                raise forbidden(ORIGIN_NOT_ALLOWED)
+        return await auth_service.authenticate_external(request)
+    token = bearer_token(request.headers)
+    if not token:
+        raise unauthorized()
+    return await auth_service.authenticate_token(token)
+
+
+def create_auth_dependencies(
+    auth_service: AuthService,
+    ensure_ready: Callable[[], Awaitable[None]] | None = None,
+) -> tuple[GetAuth, Callable[[str], Callable[..., Awaitable[AuthContext]]], GetAuth]:
+    """Return ``(get_auth, require_permission, get_auth_pending)``."""
+
+    async def get_auth_pending(request: Request) -> AuthContext:
+        if ensure_ready is not None:
+            await ensure_ready()
+        ctx = get_scope_auth(request.scope)
+        if isinstance(ctx, AuthContext):
+            return ctx
+        return await authenticate_request(auth_service, request)
+
+    async def get_auth(request: Request) -> AuthContext:
+        ctx = await get_auth_pending(request)
+        auth_service.ensure_password_changed(ctx)
+        return ctx
+
+    def require_permission(permission: str) -> Callable[..., Awaitable[AuthContext]]:
+        async def dependency(ctx: AuthContext = Depends(get_auth)) -> AuthContext:
+            if not ctx.can(permission):
+                raise forbidden(f"missing permission: {permission}")
+            return ctx
+
+        return dependency
+
+    return get_auth, require_permission, get_auth_pending
+
+
+def bearer_token_from(request: Request) -> str | None:  # backwards compat
+    return bearer_token(request.headers)

qodalis_cli_users/models.py

@@ -0,0 +1,282 @@
+"""Data models for the users plugin.
+
+Internal records are dataclasses; their ``to_dict`` methods produce the
+camelCase JSON shapes defined by the server contract shared with the node and
+.NET servers.  Request bodies are pydantic models.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+
+from pydantic import BaseModel, ConfigDict
+
+
+def now_ms() -> int:
+    """Current time in epoch milliseconds."""
+    return int(time.time() * 1000)
+
+
+def _new_id() -> str:
+    return str(uuid.uuid4())
+
+
+# ---------------------------------------------------------------------------
+# Internal records
+# ---------------------------------------------------------------------------
+
+@dataclass
+class User:
+    id: str = field(default_factory=_new_id)
+    name: str = ""
+    email: str = ""
+    groups: list[str] = field(default_factory=list)
+    disabled: bool = False
+    must_change_password: bool = False
+    home_dir: str | None = None
+    data: dict[str, Any] | None = None
+    last_login_at: int | None = None
+    created_at: int = field(default_factory=now_ms)
+    updated_at: int = field(default_factory=now_ms)
+
+    def to_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {
+            "id": self.id,
+            "name": self.name,
+            "email": self.email,
+            "groups": list(self.groups),
+            "disabled": bool(self.disabled),
+            "mustChangePassword": bool(self.must_change_password),
+            "createdAt": self.created_at,
+            "updatedAt": self.updated_at,
+        }
+        if self.home_dir is not None:
+            result["homeDir"] = self.home_dir
+        if self.last_login_at is not None:
+            result["lastLoginAt"] = self.last_login_at
+        if self.data is not None:
+            result["data"] = self.data
+        return result
+
+
+@dataclass
+class Credentials:
+    user_id: str = ""
+    #: Encoded hash, ``pbkdf2$<iterations>$<saltB64>$<hashB64>``.
+    password_hash: str = ""
+    #: Salt (base64).  Also embedded in ``password_hash``; kept for store
+    #: implementations that persist it separately.
+    salt: str = ""
+    last_changed: int = field(default_factory=now_ms)
+
+
+@dataclass
+class SessionMetadata:
+    remote_address: str | None = None
+    user_agent: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {}
+        if self.user_agent is not None:
+            result["userAgent"] = self.user_agent
+        if self.remote_address is not None:
+            result["remoteAddress"] = self.remote_address
+        return result
+
+
+@dataclass
+class Session:
+    """A stored login session.
+
+    References the user by id only; the live user record is resolved from the
+    user store on every request.  ``user_name`` is a snapshot taken at login,
+    used only as a fallback when the user can no longer be resolved.
+    """
+
+    id: str = field(default_factory=_new_id)
+    #: SHA-256 (hex) of the bearer token — the raw token is never stored.
+    token_hash: str = ""
+    user_id: str = ""
+    user_name: str = ""
+    created_at: int = field(default_factory=now_ms)
+    last_activity: int = field(default_factory=now_ms)
+    metadata: SessionMetadata = field(default_factory=SessionMetadata)
+
+    @property
+    def login_time(self) -> int:
+        return self.created_at
+
+    def expires_at(self, timeout_ms: int, max_lifetime_ms: int | None = None) -> int:
+        """``min(lastActivity + idle timeout, createdAt + max lifetime)``."""
+        idle = self.last_activity + timeout_ms
+        if max_lifetime_ms is None:
+            return idle
+        return min(idle, self.created_at + max_lifetime_ms)
+
+    def to_listing_dict(
+        self,
+        timeout_ms: int,
+        max_lifetime_ms: int | None = None,
+        *,
+        user_name: str | None = None,
+        current: bool | None = None,
+    ) -> dict[str, Any]:
+        """Listing shape — never includes the token."""
+        result: dict[str, Any] = {
+            "id": self.id,
+            "userId": self.user_id,
+            "userName": user_name if user_name is not None else self.user_name,
+            "createdAt": self.created_at,
+            "lastActivity": self.last_activity,
+            "expiresAt": self.expires_at(timeout_ms, max_lifetime_ms),
+            "metadata": (self.metadata or SessionMetadata()).to_dict(),
+        }
+        if current is not None:
+            result["current"] = current
+        return result
+
+
+@dataclass
+class AuditEntry:
+    id: str = field(default_factory=_new_id)
+    timestamp: int = field(default_factory=now_ms)
+    event: str = ""
+    username: str = ""
+    details: str | None = None
+    actor: str | None = None
+    metadata: dict[str, Any] | None = None
+    user_id: str | None = None
+    actor_id: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {
+            "id": self.id,
+            "timestamp": self.timestamp,
+            "event": self.event,
+            "username": self.username,
+        }
+        if self.user_id is not None:
+            result["userId"] = self.user_id
+        if self.actor_id is not None:
+            result["actorId"] = self.actor_id
+        if self.details is not None:
+            result["details"] = self.details
+        if self.actor is not None:
+            result["actor"] = self.actor
+        if self.metadata is not None:
+            result["metadata"] = self.metadata
+        return result
+
+
+@dataclass
+class AuditQueryOptions:
+    limit: int | None = None
+    event: str | None = None
+    username: str | None = None
+
+
+@dataclass
+class Group:
+    id: str = field(default_factory=_new_id)
+    name: str = ""
+    description: str | None = None
+    permissions: list[str] = field(default_factory=list)
+    built_in: bool = False
+    created_at: int = field(default_factory=now_ms)
+    updated_at: int = field(default_factory=now_ms)
+
+    def to_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {
+            "id": self.id,
+            "name": self.name,
+            "permissions": list(self.permissions),
+            "builtIn": bool(self.built_in),
+            "createdAt": self.created_at,
+            "updatedAt": self.updated_at,
+        }
+        if self.description is not None:
+            result["description"] = self.description
+        return result
+
+
+# ---------------------------------------------------------------------------
+# Request bodies (camelCase field names, as sent by the client)
+# ---------------------------------------------------------------------------
+
+class _Body(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+
+class LoginRequest(_Body):
+    username: str
+    password: str
+
+
+class CreateUserRequest(_Body):
+    name: str
+    email: str
+    groups: list[str] | None = None
+    password: str | None = None
+    disabled: bool | None = None
+    homeDir: str | None = None  # noqa: N815
+    data: dict[str, Any] | None = None
+
+
+class UpdateUserRequest(_Body):
+    name: str | None = None
+    email: str | None = None
+    groups: list[str] | None = None
+    disabled: bool | None = None
+    homeDir: str | None = None  # noqa: N815
+    data: dict[str, Any] | None = None
+
+
+class PasswordChangeRequest(_Body):
+    password: str | None = None
+    currentPassword: str | None = None  # noqa: N815
+    #: Admin reset only: ``False`` keeps the new password permanent;
+    #: otherwise the target must change it at next login.
+    temporary: bool | None = None
+    #: Deprecated alias of ``password`` (pre-contract clients).
+    newPassword: str | None = None  # noqa: N815
+
+
+class VerifyPasswordRequest(_Body):
+    password: str
+
+
+class CreateGroupRequest(_Body):
+    name: str
+    description: str | None = None
+    permissions: list[str] | None = None
+
+
+class UpdateGroupRequest(_Body):
+    description: str | None = None
+    permissions: list[str] | None = None
+
+
+# ---------------------------------------------------------------------------
+# External auth adapter
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ExternalAuthResult:
+    """Result returned by an external auth adapter.
+
+    ``is_admin`` adds the built-in ``admin`` group to the user's effective
+    groups (the adapter's ``user`` object is never mutated).
+    """
+
+    user: User
+    is_admin: bool = False
+
+
+# (Request) -> ExternalAuthResult | None  (may also be async)
+ExternalAuthAdapter = Callable[["Request"], Optional[ExternalAuthResult]]