dirigent-server 0.9.0__py3-none-any.whl

dirigent_server/routes/users.py

@@ -0,0 +1,226 @@
+"""Local accounts: the listing, creation, edits, activation, password resets, and their tokens."""
+
+from fastapi import APIRouter, HTTPException, Response, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from dirigent_client.schemas import (
+    IssuedTokenOut,
+    Page,
+    PasswordResetRequest,
+    TokenOut,
+    TokenRequest,
+    UserIn,
+    UserOut,
+    UserUpdate,
+)
+from dirigent_core.auth import (
+    DuplicateEmail,
+    DuplicateUser,
+    LastAdmin,
+    WeakPassword,
+    activate_user,
+    create_user,
+    deactivate_user,
+    find_user,
+    issue_token,
+    list_tokens,
+    list_users,
+    reset_password,
+    revoke_token,
+    set_email,
+    set_role,
+)
+from dirigent_core.models import User
+from dirigent_server.dependencies import SessionDep
+from dirigent_server.pagination import DEFAULT_PAGE, AfterParam, LimitParam, clip, uuid_cursor
+from dirigent_server.security import AdminDep
+from dirigent_server.transactions import Transactional
+
+router = APIRouter(route_class=Transactional, tags=["users"])
+
+
+def render(row: User) -> UserOut:
+    """Render an account row for the API."""
+    return UserOut.model_validate(row, from_attributes=True)
+
+
+async def find(session: AsyncSession, username: str) -> User:
+    """Read one account by name, or say this instance has no such account."""
+    row = await find_user(session, username)
+    if row is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"no user named {username!r}")
+    return row
+
+
+@router.get("/users", operation_id="listUsers", summary="List accounts", response_model=Page[UserOut])
+async def list_accounts(
+    session: SessionDep,
+    principal: AdminDep,
+    after: AfterParam = None,
+    limit: LimitParam = DEFAULT_PAGE,
+) -> Page[UserOut]:
+    """List every account."""
+    found = [render(row) for row in await list_users(session, after=after, limit=limit + 1)]
+    items, following = clip(found, limit, lambda row: row.username)
+    return Page(items=items, next=following)
+
+
+@router.post(
+    "/users",
+    operation_id="createUser",
+    summary="Create an account",
+    response_model=UserOut,
+    status_code=status.HTTP_201_CREATED,
+)
+async def create_account(payload: UserIn, session: SessionDep, principal: AdminDep) -> UserOut:
+    """Create an account with an Argon2id password hash."""
+    try:
+        user = await create_user(
+            session,
+            payload.username,
+            payload.password.get_secret_value(),
+            role=payload.role,
+            name=payload.name,
+            email=payload.email,
+        )
+    except (DuplicateEmail, DuplicateUser) as error:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(error)) from error
+    except WeakPassword as error:
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(error)) from error
+    return render(user)
+
+
+@router.patch("/users/{username}", operation_id="updateUser", summary="Update an account", response_model=UserOut)
+async def update_account(
+    username: str,
+    payload: UserUpdate,
+    session: SessionDep,
+    principal: AdminDep,
+) -> UserOut:
+    """Change an account's display name, email or role; the username and the password are not editable."""
+    row = await find(session, username)
+    if payload.changing("name"):
+        row.name = payload.name
+    if payload.changing("email"):
+        try:
+            await set_email(session, row, payload.email)
+        except DuplicateEmail as error:
+            raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(error)) from error
+    if payload.role is not None:
+        try:
+            await set_role(session, row, payload.role)
+        except LastAdmin as error:
+            raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(error)) from error
+    await session.flush()
+    return render(row)
+
+
+@router.post(
+    "/users/{username}/$deactivate",
+    operation_id="deactivateUser",
+    summary="Deactivate an account",
+    response_model=UserOut,
+)
+async def deactivate_account(username: str, session: SessionDep, principal: AdminDep) -> UserOut:
+    """Bar an account from logging in and revoke the sessions it already holds."""
+    row = await find(session, username)
+    try:
+        await deactivate_user(session, row)
+    except LastAdmin as error:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(error)) from error
+    return render(row)
+
+
+@router.post(
+    "/users/{username}/$activate",
+    operation_id="activateUser",
+    summary="Activate an account",
+    response_model=UserOut,
+)
+async def activate_account(username: str, session: SessionDep, principal: AdminDep) -> UserOut:
+    """Let an account log in again; the sessions it lost are not restored."""
+    return render(await activate_user(session, await find(session, username)))
+
+
+@router.post(
+    "/users/{username}/$reset-password",
+    operation_id="resetPassword",
+    summary="Reset an account's password",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def reset_account_password(
+    username: str,
+    payload: PasswordResetRequest,
+    session: SessionDep,
+    principal: AdminDep,
+) -> Response:
+    """Set an account's password without presenting the old one, ending every session it holds and no API token."""
+    row = await find(session, username)
+    try:
+        await reset_password(session, row, payload.password.get_secret_value())
+    except WeakPassword as error:
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(error)) from error
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+@router.get(
+    "/users/{username}/tokens",
+    operation_id="listUserTokens",
+    summary="List an account's API tokens",
+    response_model=Page[TokenOut],
+)
+async def list_account_tokens(
+    username: str,
+    session: SessionDep,
+    principal: AdminDep,
+    after: AfterParam = None,
+    limit: LimitParam = DEFAULT_PAGE,
+) -> Page[TokenOut]:
+    """List the API tokens one account holds, without their secrets; sessions are not listed."""
+    row = await find(session, username)
+    rows = await list_tokens(session, user_id=row.id, after=uuid_cursor(after), limit=limit + 1)
+    found = [TokenOut.model_validate(token, from_attributes=True) for token in rows]
+    items, following = clip(found, limit, lambda token: token.id)
+    return Page(items=items, next=following)
+
+
+@router.post(
+    "/users/{username}/tokens",
+    operation_id="createUserToken",
+    summary="Create an API token for an account",
+    response_model=IssuedTokenOut,
+    status_code=status.HTTP_201_CREATED,
+)
+async def create_account_token(
+    username: str,
+    payload: TokenRequest,
+    session: SessionDep,
+    principal: AdminDep,
+) -> IssuedTokenOut:
+    """Mint a bearer token for another account and return its secret exactly once."""
+    row = await find(session, username)
+    issued = await issue_token(session, row, name=payload.name)
+    return IssuedTokenOut(
+        id=issued.id,
+        name=issued.name,
+        username=issued.username,
+        prefix=issued.prefix,
+        token=issued.secret.get_secret_value(),
+    )
+
+
+@router.delete(
+    "/users/{username}/tokens/{name}",
+    operation_id="revokeUserToken",
+    summary="Revoke an account's API token",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def revoke_account_token(username: str, name: str, session: SessionDep, principal: AdminDep) -> Response:
+    """Revoke that account's live tokens of the given name."""
+    row = await find(session, username)
+    if not await revoke_token(session, user_id=row.id, name=name):
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"no live token named {name!r} for {username!r}",
+        )
+    return Response(status_code=status.HTTP_204_NO_CONTENT)

dirigent_server/routes/workers.py

@@ -0,0 +1,52 @@
+"""The worker registry: who is alive, on what version, with which plugins and tags."""
+
+import sqlalchemy as sa
+from fastapi import APIRouter
+
+from dirigent_client.enums import WorkerStatus
+from dirigent_client.schemas import Page, WorkerOut
+from dirigent_core.models import Worker, utcnow
+from dirigent_core.registry import STALE_AFTER
+from dirigent_server.dependencies import ServicesDep, SessionDep
+from dirigent_server.pagination import DEFAULT_PAGE, AfterParam, LimitParam, clip
+from dirigent_server.security import PrincipalDep
+from dirigent_server.transactions import Transactional
+
+router = APIRouter(route_class=Transactional, tags=["workers"])
+
+
+@router.get("/workers", operation_id="listWorkers", summary="List workers", response_model=Page[WorkerOut])
+async def list_workers(
+    session: SessionDep,
+    services: ServicesDep,
+    principal: PrincipalDep,
+    after: AfterParam = None,
+    limit: LimitParam = DEFAULT_PAGE,
+) -> Page[WorkerOut]:
+    """List the worker registry, flagging anything stale or running different code."""
+    digest = services.host.catalog().digest
+    cutoff = utcnow() - STALE_AFTER
+    statement = sa.select(Worker).order_by(Worker.name).limit(limit + 1)
+    if after is not None:
+        statement = statement.where(Worker.name > after)
+    rows = await session.execute(statement)
+    found = [
+        WorkerOut(
+            id=row.id,
+            name=row.name,
+            hostname=row.hostname,
+            version=row.version,
+            status=row.status,
+            concurrency=row.concurrency,
+            tags=list(row.tags),
+            plugins=dict(row.plugins),
+            catalog_digest=row.catalog_digest,
+            code_matches_server=row.catalog_digest == digest,
+            stale=row.last_seen_at < cutoff and row.status is not WorkerStatus.STOPPED,
+            created_at=row.created_at,
+            last_seen_at=row.last_seen_at,
+        )
+        for row in rows.scalars()
+    ]
+    items, following = clip(found, limit, lambda row: row.name)
+    return Page(items=items, next=following)

dirigent_server/security.py

@@ -0,0 +1,186 @@
+"""Authentication and the three roles: a session cookie for the UI, a bearer token for automation.
+
+Every route under the versioned API requires a principal. The only exemptions are the
+health probes, the OpenAPI document and its viewers, and the login endpoint.
+
+A viewer may read: every GET, the event streams, exports and reports, and whatever acts on
+the caller's own credential. An operator may in addition define, apply, run, cancel, retry
+and schedule. Anything that hands out authority -- accounts, API tokens, connections,
+schemas -- and deleting a pipeline require admin.
+
+The session cookie is an ambient credential: a browser attaches it to a request another
+site's page caused. So a write that spends it has to say it came from this instance, which
+is what the cross-site guard below requires. A bearer token is not ambient and is exempt.
+"""
+
+from collections.abc import Awaitable, Callable
+from typing import Annotated
+
+from fastapi import FastAPI, HTTPException, Request, Response, Security, status
+from fastapi.security import APIKeyCookie, HTTPAuthorizationCredentials, HTTPBearer
+
+from dirigent_core.auth import Principal, resolve_token
+from dirigent_core.config import Settings
+from dirigent_core.logging import redact_path
+from dirigent_server.dependencies import SessionDep
+from dirigent_server.errors import answer, render
+
+SESSION_COOKIE = "dirigent_session"
+
+BEARER_PREFIX = "Bearer "
+
+#: Must not hint at which credential would have worked.
+UNAUTHENTICATED = "authentication required: present a bearer token or log in"
+
+#: One detail for both role refusals, saying neither which role would have sufficed nor what
+#: any role may do: a refusal is not the place to teach the permission model.
+FORBIDDEN = "not permitted for your role"
+
+#: Declared so the schemes reach the OpenAPI document; without them every operation renders
+#: as open and a generated client has no place to put a token. ``auto_error=False`` on both,
+#: so that :func:`require_principal` remains the one place a request is refused.
+bearer_scheme = HTTPBearer(
+    scheme_name="bearerAuth",
+    description="An API token from `dg admin token create`, presented as `Authorization: Bearer <token>`.",
+    auto_error=False,
+)
+cookie_scheme = APIKeyCookie(
+    name=SESSION_COOKIE,
+    scheme_name="sessionCookie",
+    description="The http-only session cookie `POST /auth/login` sets, which the UI uses.",
+    auto_error=False,
+)
+
+
+#: Methods that change state, and so may not be caused by another site's page.
+UNSAFE_METHODS = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+
+#: What a browser reports for a request that no other site initiated: a same-origin fetch,
+#: or a typed URL, bookmark or redirect, which is ``none``.
+SAME_SITE_FETCH = frozenset({"same-origin", "none"})
+
+#: Login is guarded although it carries no session yet: a cross-site login POST logs a
+#: person into an account the attacker controls, and every later action is attributed there.
+LOGIN_PATH = "/auth/login"
+
+CROSS_SITE = (
+    "this write was initiated by another site, and a session cookie may not be spent across "
+    "origins; automation authenticating with a bearer token is unaffected"
+)
+
+
+def presented_secret(request: Request) -> str | None:
+    """Read the credential from the request: an Authorization header, or the session cookie."""
+    header = request.headers.get("authorization")
+    if header and header.startswith(BEARER_PREFIX):
+        return header[len(BEARER_PREFIX) :].strip() or None
+    return request.cookies.get(SESSION_COOKIE)
+
+
+async def optional_principal(
+    request: Request,
+    session: SessionDep,
+    _bearer: Annotated[HTTPAuthorizationCredentials | None, Security(bearer_scheme)] = None,
+    _cookie: Annotated[str | None, Security(cookie_scheme)] = None,
+) -> Principal | None:
+    """Resolve who is asking, or nothing when no usable credential was presented.
+
+    The two unused scheme parameters are what put the security schemes in the OpenAPI
+    document; the credential itself is read from the request.
+    """
+    secret = presented_secret(request)
+    if secret is None:
+        return None
+    return await resolve_token(session, secret)
+
+
+async def require_principal(principal: Annotated[Principal | None, Security(optional_principal)]) -> Principal:
+    """Refuse a request that carries no valid credential."""
+    if principal is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=UNAUTHENTICATED,
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return principal
+
+
+async def require_operator(principal: Annotated[Principal, Security(require_principal)]) -> Principal:
+    """Refuse a request from an account that may only read."""
+    if not principal.may_operate:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=FORBIDDEN)
+    return principal
+
+
+async def require_admin(principal: Annotated[Principal, Security(require_principal)]) -> Principal:
+    """Refuse a request from an account that may not manage accounts, tokens, or connections."""
+    if not principal.is_admin:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=FORBIDDEN)
+    return principal
+
+
+def initiated_elsewhere(request: Request) -> bool:
+    """Whether a browser says another site caused this request.
+
+    Fetch metadata is the answer when the browser sends it; ``Origin`` is the fallback, and
+    a request carrying neither is not from a browser at all.
+    """
+    site = request.headers.get("sec-fetch-site")
+    if site is not None:
+        return site not in SAME_SITE_FETCH
+    origin = request.headers.get("origin")
+    if origin is None:
+        return False
+    return origin.rstrip("/").lower() != f"{request.url.scheme}://{request.url.netloc}".lower()
+
+
+def spends_the_cookie(request: Request, api_prefix: str) -> bool:
+    """Whether this request is a write under the API that a session cookie would authenticate."""
+    if request.method not in UNSAFE_METHODS or not request.url.path.startswith(api_prefix):
+        return False
+    if request.url.path == f"{api_prefix.rstrip('/')}{LOGIN_PATH}":
+        return True
+    header = request.headers.get("authorization")
+    if header and header.startswith(BEARER_PREFIX):
+        return False
+    return SESSION_COOKIE in request.cookies
+
+
+def install_cross_site_guard(app: FastAPI, settings: Settings) -> None:
+    """Refuse a state-changing request that a cookie would authenticate and another site caused.
+
+    Registered before the error handlers, so the version-header middleware they install wraps
+    this refusal too.
+    """
+    prefix = settings.api_prefix
+
+    @app.middleware("http")
+    async def guard(  # pyright: ignore[reportUnusedFunction]
+        request: Request, call_next: Callable[[Request], Awaitable[Response]]
+    ) -> Response:
+        if spends_the_cookie(request, prefix) and initiated_elsewhere(request):
+            return answer(render(status.HTTP_403_FORBIDDEN, CROSS_SITE, instance=redact_path(request.url.path)))
+        return await call_next(request)
+
+
+def set_session_cookie(response: Response, secret: str, *, max_age: int, secure: bool) -> None:
+    """Attach a session cookie that JavaScript cannot read and another site cannot send."""
+    response.set_cookie(
+        SESSION_COOKIE,
+        secret,
+        max_age=max_age,
+        httponly=True,
+        samesite="lax",
+        secure=secure,
+        path="/",
+    )
+
+
+def clear_session_cookie(response: Response) -> None:
+    """Remove the session cookie."""
+    response.delete_cookie(SESSION_COOKIE, path="/")
+
+
+PrincipalDep = Annotated[Principal, Security(require_principal)]
+OperatorDep = Annotated[Principal, Security(require_operator)]
+AdminDep = Annotated[Principal, Security(require_admin)]

dirigent_server/transactions.py

@@ -0,0 +1,34 @@
+"""Where a request's transaction is committed: before its response, not after."""
+
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from fastapi import Request, Response
+from fastapi.routing import APIRoute
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+class Transactional(APIRoute):
+    """A route that commits its request's transaction before the response is sent.
+
+    The alternative is to commit in the exit of the dependency that opened it, which FastAPI
+    runs after the response has gone out. Two things follow from that, and both are wrong: a
+    client that reads straight back can miss the write it was just told about, and a commit
+    that fails does so after the client has a 2xx it will believe.
+
+    Committing here happens while the response can still be changed, so a commit that fails
+    is the error the client sees.
+    """
+
+    def get_route_handler(self) -> Callable[[Request], Coroutine[Any, Any, Response]]:
+        """Wrap the handler so what it decided is durable before anybody is told."""
+        handle = super().get_route_handler()
+
+        async def commit_then_respond(request: Request) -> Response:
+            response = await handle(request)
+            session: AsyncSession | None = getattr(request.state, "session", None)
+            if session is not None and session.in_transaction():
+                await session.commit()
+            return response
+
+        return commit_then_respond