perfact-api-main 0.2__tar.gz

perfact_api_main-0.2/.gitea/workflows/check.yml

@@ -0,0 +1,35 @@
+name: Tox tests
+on:
+  push:
+    branches:
+      - 'main'
+  pull_request: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+
+    steps:
+    - name: Install SSH key
+      run: |
+        mkdir -p /root/.ssh
+        printf '%s' '${{ secrets.SSH_DEPLOYMENT_KEY }}' > /root/.ssh/id_rsa
+        printf '%s' '${{ secrets.KNOWN_HOSTS }}' > /root/.ssh/known_hosts
+        chmod 600 /root/.ssh/id_rsa
+
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install tox tox-gh-actions
+    - name: Test with tox
+      run: |
+        ls -lh /root/.ssh
+        tox

perfact_api_main-0.2/.gitignore

@@ -0,0 +1,7 @@
+tags*
+*.egg-info
+__pycache__
+.tox
+.ruff_cache
+.mypy_cachebuild
+build

perfact_api_main-0.2/.vscode/launch.json

@@ -0,0 +1,41 @@
+{
+    // Verwendet IntelliSense zum Ermitteln möglicher Attribute.
+    // Zeigen Sie auf vorhandene Attribute, um die zugehörigen Beschreibungen anzuzeigen.
+    // Weitere Informationen finden Sie unter https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+
+        {
+            "name": "FastAPI: App",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "uvicorn",
+            "args": [
+                "perfact.api.main.app:app",
+                "--reload",
+                "--reload-include",
+                "../"
+            ],
+            "jinja": true,
+            "env": {
+                "PERFACT_API_CONFIG_PATH": "./config.yaml"
+            }
+        },
+        {
+            "name": "FastAPI: Assignworker",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "uvicorn",
+            "args": [
+                "perfact.api.main.assignworker:app",
+                "--reload",
+                "--reload-include",
+                "../"
+            ],
+            "jinja": true,
+            "env": {
+                "PERFACT_API_CONFIG_PATH": "./config.yaml"
+            }
+        }
+    ]
+}

perfact_api_main-0.2/.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "[python]": {
+        "editor.defaultFormatter": "charliermarsh.ruff",
+        "editor.formatOnSave": true
+    }
+}

perfact_api_main-0.2/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: perfact-api-main
+Version: 0.2
+Summary: PerFact API - FastAPI main package (middleware, auth, entrypoints)
+Author-email: Viktor Dick <viktor.dick@perfact.de>
+License-Expression: GPL-2.0-or-later
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: SQL
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: argon2-cffi
+Requires-Dist: psycopg[c]
+Requires-Dist: fastapi[standard-no-fastapi-cloud-cli]
+Requires-Dist: sqlalchemy
+Requires-Dist: pydantic-settings
+Requires-Dist: perfact-api-app-model
+
+# PerFact API Base
+The main FastAPI package for the PerFact API. Provides authentication, authorisation, database session handling, and plugin discovery. All domain-specific API modules are in separate packages and loaded automatically at startup via entry points.
+
+## Applications
+
+### `perfact.api.main.app` — user-facing API
+
+Hosts all plugins registered under the `perfact.api` entry point group. Users authenticate via a login cookie or an `Authorization: Apikey …` header. Access to individual endpoints can be restricted by role:
+
+```python
+from perfact.api.main.auth import require_roles
+
+@router.get("/my-endpoint")
+@require_roles("MyRole")
+def my_endpoint(session: DBSession) -> ...:
+    ...
+```
+
+### `perfact.api.main.assignworker` — task runner API
+
+Hosts all plugins registered under the `perfact.assignapi` entry point group. Intended for internal use by `assignd`. Authentication is HTTP Basic Auth with a pre-shared password hash configured in the YAML config file.
+
+## Plugin discovery
+
+At startup, both apps iterate over their respective entry point group and call `mount(app)` on each discovered plugin:
+
+```
+INFO - start plugin discovery
+INFO - try to include plugin: perfact.api.pd.routes:mount
+INFO - finished discovery and include: 1 plugins
+```
+
+A plugin registers itself by declaring an entry point in its `pyproject.toml`:
+
+```toml
+[project.entry-points.'perfact.api']
+myplugin = 'perfact.api.myplugin.routes:mount'
+```
+
+## getting started as developer
+After you checked out this repository, do the following steps to be able to debug your application:
+1. create and activate *venv*
+    ```sh
+    python -m venv .venv
+
+    source .venv/bin/activate # linux
+    .venv/Scripts/Activate.ps1 # PowerShell
+    ```
+1. Install the API plugins you want to include without doing changes by installing them from pypi:
+    ```sh
+    pip install perfact-api-base-model
+    ```
+1. Install the API plugins you want to include and **change** in your instance by checking them out somewhere and installing/linking them into your application via `pip install -e`:
+    ```sh
+    pip install -e ../perfact-api-base-model/ # required
+    pip install -e ../perfact-api-app-model/ # required
+    pip install -e ../perfact-api-pd-model/ # example
+    ```
+
+**Hint**: Every code change is available in the application after the next restart/reload. Changes to the entrypoints are available after the next install command execution (as this is recreating the `ENTRYPOINTS`-file belonging to the package in the site-packages folder).
+
+You can install as much as plugins you like, even custom ones.
+
+*pip* will automaticly check if more dependencies needed by the plugin while installing, e.g.
+```
+Requirement already satisfied: fastapi
+```
+
+
+Now you can run the application:
+```
+uvicorn perfact.api.main.app:app # run API for frontend
+uvicorn perfact.api.main.assignworker:app # run API for assignd worker APIs
+uvicorn perfact.api.main.app:app  --reload --reload-include ../ # run API for frontend with auto-reload for all editable dependencies
+```
+
+There is a `launch.json`-file provided to debug the application in VS Code. To use that, you have to create a configuration file (see below).
+
+## Configuration
+The application can be configured by providing a configuration yaml-File containing informations about the database connection and basic auth credentials (for `assignworker`).
+The configuration file is given to the application by providing the location (absolute or relative to working dir) in the environment variable `PERFACT_API_CONFIG_PATH`.
+
+Example:
+```yaml
+connstr: postgresql+psycopg://zope@/perfactema # default, can be left out
+basicauth: "$argon2id$v=19$m=65536,t=3,p=4$6itEouPTNwWEXDKScKmMrw$NwhN1vAUN8EZjC62HrtXjx7n+K1Mujjd/QqioaHvyOg" # password=test
+```
+
+## Dependencies
+- `perfact-api-app-model`
+- `fastapi`
+- `sqlalchemy`
+- `psycopg[c]`
+- `argon2-cffi`
+- `pydantic-settings`
+
+## Maintainers
+- Viktor Dick <viktor.dick@perfact.de>
+- Alexander Rolfes <alexander.rolfes@perfact.de>

perfact_api_main-0.2/README.md

@@ -0,0 +1,99 @@
+# PerFact API Base
+The main FastAPI package for the PerFact API. Provides authentication, authorisation, database session handling, and plugin discovery. All domain-specific API modules are in separate packages and loaded automatically at startup via entry points.
+
+## Applications
+
+### `perfact.api.main.app` — user-facing API
+
+Hosts all plugins registered under the `perfact.api` entry point group. Users authenticate via a login cookie or an `Authorization: Apikey …` header. Access to individual endpoints can be restricted by role:
+
+```python
+from perfact.api.main.auth import require_roles
+
+@router.get("/my-endpoint")
+@require_roles("MyRole")
+def my_endpoint(session: DBSession) -> ...:
+    ...
+```
+
+### `perfact.api.main.assignworker` — task runner API
+
+Hosts all plugins registered under the `perfact.assignapi` entry point group. Intended for internal use by `assignd`. Authentication is HTTP Basic Auth with a pre-shared password hash configured in the YAML config file.
+
+## Plugin discovery
+
+At startup, both apps iterate over their respective entry point group and call `mount(app)` on each discovered plugin:
+
+```
+INFO - start plugin discovery
+INFO - try to include plugin: perfact.api.pd.routes:mount
+INFO - finished discovery and include: 1 plugins
+```
+
+A plugin registers itself by declaring an entry point in its `pyproject.toml`:
+
+```toml
+[project.entry-points.'perfact.api']
+myplugin = 'perfact.api.myplugin.routes:mount'
+```
+
+## getting started as developer
+After you checked out this repository, do the following steps to be able to debug your application:
+1. create and activate *venv*
+    ```sh
+    python -m venv .venv
+
+    source .venv/bin/activate # linux
+    .venv/Scripts/Activate.ps1 # PowerShell
+    ```
+1. Install the API plugins you want to include without doing changes by installing them from pypi:
+    ```sh
+    pip install perfact-api-base-model
+    ```
+1. Install the API plugins you want to include and **change** in your instance by checking them out somewhere and installing/linking them into your application via `pip install -e`:
+    ```sh
+    pip install -e ../perfact-api-base-model/ # required
+    pip install -e ../perfact-api-app-model/ # required
+    pip install -e ../perfact-api-pd-model/ # example
+    ```
+
+**Hint**: Every code change is available in the application after the next restart/reload. Changes to the entrypoints are available after the next install command execution (as this is recreating the `ENTRYPOINTS`-file belonging to the package in the site-packages folder).
+
+You can install as much as plugins you like, even custom ones.
+
+*pip* will automaticly check if more dependencies needed by the plugin while installing, e.g.
+```
+Requirement already satisfied: fastapi
+```
+
+
+Now you can run the application:
+```
+uvicorn perfact.api.main.app:app # run API for frontend
+uvicorn perfact.api.main.assignworker:app # run API for assignd worker APIs
+uvicorn perfact.api.main.app:app  --reload --reload-include ../ # run API for frontend with auto-reload for all editable dependencies
+```
+
+There is a `launch.json`-file provided to debug the application in VS Code. To use that, you have to create a configuration file (see below).
+
+## Configuration
+The application can be configured by providing a configuration yaml-File containing informations about the database connection and basic auth credentials (for `assignworker`).
+The configuration file is given to the application by providing the location (absolute or relative to working dir) in the environment variable `PERFACT_API_CONFIG_PATH`.
+
+Example:
+```yaml
+connstr: postgresql+psycopg://zope@/perfactema # default, can be left out
+basicauth: "$argon2id$v=19$m=65536,t=3,p=4$6itEouPTNwWEXDKScKmMrw$NwhN1vAUN8EZjC62HrtXjx7n+K1Mujjd/QqioaHvyOg" # password=test
+```
+
+## Dependencies
+- `perfact-api-app-model`
+- `fastapi`
+- `sqlalchemy`
+- `psycopg[c]`
+- `argon2-cffi`
+- `pydantic-settings`
+
+## Maintainers
+- Viktor Dick <viktor.dick@perfact.de>
+- Alexander Rolfes <alexander.rolfes@perfact.de>

perfact_api_main-0.2/bandit.yml

@@ -0,0 +1,2 @@
+assert_used:
+  skips: ["*/test_*.py"]

perfact_api_main-0.2/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=61.2", "setuptools-scm>=8.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "perfact-api-main"
+authors = [
+    {name="Viktor Dick", email="viktor.dick@perfact.de"},
+]
+description = "PerFact API - FastAPI main package (middleware, auth, entrypoints)"
+readme = "README.md"
+license = "GPL-2.0-or-later"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: SQL",
+    "Operating System :: POSIX :: Linux",
+]
+dependencies = [
+    "argon2-cffi",
+    "psycopg[c]",
+    "fastapi[standard-no-fastapi-cloud-cli]",
+    "sqlalchemy",
+    "pydantic-settings",
+    "perfact-api-app-model",
+]
+dynamic = ["version"]
+requires-python = ">=3.10"
+
+[project.scripts]
+
+[tool.distutils.bdist_wheel]
+universal = 1
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools_scm]
+
+[tool.ruff]
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]

perfact_api_main-0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

perfact_api_main-0.2/src/perfact/api/main/__init__.py

@@ -0,0 +1,4 @@
+from .auth import Auth, require_roles
+from .dbsession import DBSession
+
+__all__ = ["require_roles", "Auth", "DBSession"]

perfact_api_main-0.2/src/perfact/api/main/app.py

@@ -0,0 +1,42 @@
+import logging
+
+from fastapi import FastAPI, Response, status
+
+from .auth import (
+    Auth,
+    SameSitePostMiddleware,
+    add_403_to_openapi,
+)
+from .config import Configuration
+from .dbsession import DBSessionMiddleware, set_connstr
+from .utils import default_logging_settings, discover_add_routes_from_entrypoint
+
+default_logging_settings()
+
+log = logging.getLogger(__name__)
+
+
+def lifespan(app: FastAPI):
+    config = Configuration()
+    set_connstr(config.get_connection_string())
+
+    discover_add_routes_from_entrypoint(app, "perfact.api")
+
+    add_403_to_openapi(app)
+    yield
+
+
+app = FastAPI(title="PerFact API", lifespan=lifespan)
+app.add_middleware(DBSessionMiddleware)
+app.add_middleware(SameSitePostMiddleware)
+
+
+@app.get("/user/roles")
+async def roles(user: Auth, response: Response) -> list[str]:
+    """
+    Return list of roles the user has. Returns Unauthorized if no user is found
+    """
+    if user is None:
+        response.status_code = status.HTTP_401_UNAUTHORIZED
+        return []
+    return user.roles

perfact_api_main-0.2/src/perfact/api/main/assignworker.py

@@ -0,0 +1,63 @@
+import logging
+
+from argon2 import PasswordHasher
+from fastapi import Depends, FastAPI, HTTPException, status
+from fastapi.security import HTTPBasic, HTTPBasicCredentials
+from pydantic_settings import BaseSettings
+
+from .config import Configuration
+from .dbsession import DBSessionMiddleware, set_connstr
+from .utils import default_logging_settings, discover_add_routes_from_entrypoint
+
+default_logging_settings()
+
+
+log = logging.getLogger(__name__)
+
+
+class Settings(BaseSettings):
+    pwhash: str = ""
+
+
+settings = Settings()
+
+
+def lifespan(app: FastAPI):
+    config = Configuration()
+    set_connstr(config.get_connection_string())
+    settings.pwhash = config.get_basic_auth_credentials_secret()
+
+    discover_add_routes_from_entrypoint(app, "perfact.assignapi")
+
+    yield
+
+
+basic_auth = HTTPBasic()
+
+
+def _verify_credentials(credentials: HTTPBasicCredentials = Depends(basic_auth)):
+    ph = PasswordHasher()
+    try:
+        ph.verify(settings.pwhash, credentials.password)
+    except Exception as _:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect username or password",
+            headers={"WWW-Authenticate": "Basic"},
+        )
+
+
+app = FastAPI(
+    lifespan=lifespan,
+    title="PerFact API for assignd (task runner)",
+    dependencies=[Depends(_verify_credentials)],
+)
+app.add_middleware(DBSessionMiddleware)
+
+
+@app.get("/test")
+async def test() -> bool:
+    """
+    Returns True if  the authentification is valid; otherwise Unauthorized.
+    """
+    return True

perfact_api_main-0.2/src/perfact/api/main/auth.py

@@ -0,0 +1,346 @@
+import inspect
+import os
+from dataclasses import dataclass
+from functools import wraps
+from typing import Annotated, Callable, Optional, TypeVar
+
+import argon2
+from fastapi import Depends, Header, HTTPException, Query, Response, status
+from fastapi.routing import APIRoute
+from fastapi.security import APIKeyCookie, APIKeyHeader
+from perfact.api.app.model import (
+    AppGroup,
+    AppPermXGroup,
+    AppPermXStc,
+    AppStc,
+    AppStc_Paths,
+    AppUser,
+    AppUserKey,
+    AppUserLogin,
+    AppUserXPerm,
+    AppUserXStc,
+)
+from pydantic import BaseModel, Field
+from sqlalchemy import (
+    any_,
+    func,
+    not_,
+    or_,
+    select,
+)
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import JSONResponse
+
+from .dbsession import DBSession
+from .perfact_generic import secret_check_sha1
+
+COOKIE = "__user_cookie"
+DUMMY_HASH = argon2.PasswordHasher().hash(os.urandom(16).hex())
+
+LoginCookieDep = Annotated[
+    str,
+    Depends(
+        APIKeyCookie(name=COOKIE, description="Generated by /login", auto_error=False)
+    ),
+]
+ApikeyHeaderDep = Annotated[
+    str,
+    Depends(APIKeyHeader(name="Authorization", auto_error=False)),
+]
+
+
+class ContextParams(BaseModel):
+    appstc_id: Optional[int] = Field(default=None, alias="__appstc_id")
+
+
+ContextParamsDep = Annotated[ContextParams, Query()]
+
+
+def _get_appperm_grant(
+    appperm_grant: Annotated[list[int] | None, Header(alias="x-appperm-grant")] = None,
+) -> list[int]:
+    return appperm_grant or []
+
+
+AppPermGrantDep = Annotated[list[int], Depends(_get_appperm_grant)]
+
+
+@dataclass
+class AuthInfo:
+    """
+    Authentication information for the current user
+    """
+
+    name: str
+    roles: list[str]
+    appstc: Optional[AppStc]
+
+
+def _auth_apikey(session: DBSession, key: str) -> Optional[AppUser]:
+    """
+    Split provided Apikey on first dash. The first part is an identifier so we only
+    check keys in the database that have the same initial part.
+    The rest is checked against the hashed value in the database.
+    TODO: Our database does not actually have Argon2 hashes yet, we need to
+    also check for ssha.
+    """
+    if not key.startswith("Apikey "):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid authorization header",
+        )
+    key = key.split()[1]
+    ident, key = key.split("-", 1)
+    candidates = session.execute(
+        select(AppUserKey, AppUser)
+        .where(func.regexp_match(AppUserKey.key, (ident + "-.*")).isnot(None))
+        .where(AppUserKey.appuser_id == AppUser.id)
+    )
+    hasher = argon2.PasswordHasher()
+    if not candidates:
+        try:
+            hasher.verify(DUMMY_HASH, key)
+        except argon2.exceptions.VerifyMismatchError:
+            pass
+        return None
+    for appuserkey, appuser in candidates:
+        _, encrypted = appuserkey.key.split("-", 1)
+        try:
+            hasher.verify(encrypted, key)
+            return appuser
+        except argon2.exceptions.VerifyMismatchError:
+            pass
+        except argon2.exceptions.InvalidHashError:
+            pass
+        if secret_check_sha1(encrypted, key):
+            return appuser
+    return None
+
+
+def _auth_cookie(
+    session: DBSession, cookie: str, response: Response
+) -> Optional[AppUser]:
+    """
+    Compare user cookie against appuserlogin_cookie and appuserlogin_nextcookie.
+    If the user sent nextcookie, rotate them (assuming that from now on the old
+    cookie will no longer be sent). In any case, set the cookie to be used in
+    the future in the response (there was something about browsers sometimes no
+    longer sending a cookie if we don't remind them with every request that
+    this cookie is to be set).
+    """
+    row = session.execute(
+        select(AppUserLogin, AppUser)
+        .join_from(AppUserLogin, AppUser)
+        .where(
+            or_(
+                AppUserLogin.cookie == cookie,
+                AppUserLogin.nextcookie == cookie,
+            ),
+            not_(AppUserLogin.done),
+        )
+    ).first()
+    if not row:
+        return None
+    login, user = row
+
+    send_cookie = login.nextcookie or login.cookie
+    if cookie == login.nextcookie:
+        login.cookie = login.nextcookie
+        login.nextcookie = None
+
+    response.set_cookie(
+        key=COOKIE,
+        value=send_cookie,
+        httponly=True,
+        secure=True,
+        samesite="strict",
+    )
+    return user
+
+
+def _process_auth(
+    session: DBSession,
+    cookie: LoginCookieDep,
+    apikey: ApikeyHeaderDep,
+    params: ContextParamsDep,
+    response: Response,
+    appperm_grant: AppPermGrantDep,
+) -> Optional[AuthInfo]:
+    """
+    Process authorization at the beginning of (essentially) every request.
+    (If a path does not depend on Auth, it is accessible anonymously)
+    1) Check for user using either a login cookie or an API key
+    2) Check appstc (organization area). If an appstc_id is provided, check that the
+       user is allowed to activate it. Otherwise select a default appstc
+    3) Check which roles the user has in this appstc
+    """
+    appuser = None
+    if apikey is not None:
+        appuser = _auth_apikey(session, apikey)
+    elif cookie is not None:
+        appuser = _auth_cookie(session, cookie, response)
+
+    if not appuser:
+        return None
+
+    # Check for appstc
+    appstc_id: int | None = params.appstc_id
+    if appstc_id:
+        if not session.execute(
+            select(
+                select(1)
+                .select_from(AppUserXStc)
+                .join(AppStc_Paths, AppUserXStc.appstc_id == any_(AppStc_Paths.id_path))
+                .where(AppStc_Paths.id == appstc_id)
+                .where(AppUserXStc.appuser_id == appuser.id)
+                .exists()
+            )
+        ).scalar():
+            appstc_id = None
+    else:
+        # Find the "first" appstc for the user
+        appstc_id = session.execute(
+            select(AppUserXStc.appstc_id)
+            .join(AppStc_Paths, AppUserXStc.appstc_id == AppStc_Paths.id)
+            .where(AppUserXStc.appuser_id == appuser.id)
+            .order_by(AppStc_Paths.depth, AppStc_Paths.id_path)
+            .limit(1)
+        ).scalar()
+
+    roles: list[str] = []
+    if appstc_id:
+        rows = session.execute(
+            select(func.array_agg(AppGroup.zoperole))
+            .join(AppPermXGroup, AppPermXGroup.appgroup_id == AppGroup.id)
+            .join(
+                AppUserXPerm,
+                (AppUserXPerm.appperm_id == AppPermXGroup.appperm_id)
+                & (AppUserXPerm.appuser_id == appuser.id)
+                & (
+                    not_(AppUserXPerm.needsgrant)
+                    | AppUserXPerm.appperm_id.in_(appperm_grant)
+                ),
+            )
+            .join(AppPermXStc, AppPermXStc.appperm_id == AppPermXGroup.appperm_id)
+            .join(
+                AppStc_Paths,
+                (AppPermXStc.appstc_id == any_(AppStc_Paths.id_path))
+                & (AppStc_Paths.id == appstc_id),
+            )
+        ).all()
+        roles = rows[0][0] or []
+
+    appstc = None
+    if appstc_id:
+        appstc = session.execute(
+            select(AppStc).where(AppStc.id == appstc_id)
+        ).scalar_one()
+        response.headers["X-PerFact-stc"] = str(appstc.id)
+
+    result = AuthInfo(name=appuser.name, roles=roles, appstc=appstc)
+    # We commit here, so the authentication phase and the payload phase are
+    # done in separate transactions.
+    session.commit()
+    return result
+
+
+Auth = Annotated[Optional[AuthInfo], Depends(_process_auth)]
+
+
+_F = TypeVar("_F", bound=Callable[..., object])
+
+
+def require_roles(*roles: str) -> Callable[[_F], _F]:
+    """
+    Decorator to check for given roles
+    """
+
+    def require(required: tuple[str, ...]):
+
+        def checker(user: Auth):
+            # Check if all required scopes are present
+            roles = set() if user is None else user.roles
+            missing = set(required) - set(roles)
+            if missing:
+                raise HTTPException(
+                    status_code=403,
+                    detail={
+                        "msg": "Missing required permissions",
+                        "missing": list(missing),
+                    },
+                )
+
+            return True
+
+        return checker
+
+    dep = Depends(require(roles))
+
+    def decorator(func: _F) -> _F:
+        sig = inspect.signature(func)
+
+        # create a new parameter for the dependency (keyword-only)
+        dep_param = inspect.Parameter(
+            "scope_check",
+            kind=inspect.Parameter.KEYWORD_ONLY,
+            annotation=Annotated[None, dep],
+        )
+
+        # build new signature: keep original params, append dep_param
+        params = list(sig.parameters.values()) + [dep_param]
+        new_sig = sig.replace(parameters=params)
+
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            # remove scope_check if present before calling original func
+            kwargs.pop("scope_check", None)
+            return func(*args, **kwargs)
+
+        # attach the new signature so FastAPI sees the dependency
+        wrapper.__signature__ = new_sig  # type: ignore
+        # Inject OpenAPI metadata
+        wrapper.__dict__["required_roles"] = roles
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+def add_403_to_openapi(app):
+    """
+    Call this after all routes are added.
+    """
+    for route in app.routes:
+        if isinstance(route, APIRoute):
+            endpoint = route.endpoint
+            roles = getattr(endpoint, "required_roles", None)
+            if roles:
+                # Add 403 response if not already present
+                if route.openapi_extra is None:
+                    route.openapi_extra = {}
+                route.openapi_extra["x-required-roles"] = roles
+                route.responses.setdefault(
+                    403,
+                    {
+                        "description": "Forbidden – missing required permissions",
+                        "model": list[str],
+                    },
+                )
+
+
+class SameSitePostMiddleware(BaseHTTPMiddleware):
+    """
+    Rejects POST/PUT/PATCH requests from browser clients where Sec-Fetch-Site
+    is present but not "same-origin". Non-browser clients (no Sec-Fetch-Site
+    header) are not subject to CSRF and are allowed through.
+    """
+
+    async def dispatch(self, request, call_next):
+        if request.method in ("POST", "PUT", "PATCH"):
+            sec_fetch_site = request.headers.get("sec-fetch-site")
+            if sec_fetch_site is not None and sec_fetch_site != "same-origin":
+                return JSONResponse(
+                    status_code=401,
+                    content={"detail": f"Unauthorized: cross-site {request.method}"},
+                )
+
+        return await call_next(request)

perfact_api_main-0.2/src/perfact/api/main/config.py

@@ -0,0 +1,34 @@
+import logging
+import os
+
+import yaml
+
+log = logging.getLogger(__name__)
+
+
+class Configuration:
+    def __init__(self):
+        """
+        Reads environment variable for path to
+        config and reads the configuration file from there.
+        """
+        config_path = os.environ.get("PERFACT_API_CONFIG_PATH")
+        if not config_path:
+            log.warning("No configuration file detected. Use default configuration.")
+            self.config = {}
+            return
+        log.info(f"Use configuration from file: {config_path}")
+        with open(config_path) as f:
+            self.config = yaml.safe_load(f)
+
+    def get_connection_string(self) -> str | None:
+        """returns the connection string if configured"""
+        if "connstr" not in self.config:
+            return None
+        return self.config["connstr"]
+
+    def get_basic_auth_credentials_secret(self) -> str:
+        """returns the auth hash if configured"""
+        if "basicauth" not in self.config:
+            raise RuntimeError("No auth hash configured!")
+        return self.config["basicauth"]

perfact_api_main-0.2/src/perfact/api/main/dbsession.py

@@ -0,0 +1,61 @@
+from typing import Annotated
+
+from fastapi import Depends, Request, Response
+from pydantic_settings import BaseSettings
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Session
+from sqlalchemy.pool import NullPool
+from starlette.middleware.base import BaseHTTPMiddleware
+
+
+class Settings(BaseSettings):
+    connstr: str = "postgresql+psycopg://zope@/perfactema"
+    sql_debug: bool = False
+    pooling: bool = True  # Set to False for testing
+
+
+settings = Settings()
+
+
+def set_connstr(connstr):
+    """
+    To be called before the app starts up,
+    set the connection string from there.
+    """
+    if connstr:
+        settings.connstr = connstr
+
+
+class DBSessionMiddleware(BaseHTTPMiddleware):
+    """
+    Start a DB session for each request. Commit it at the end if there is no error,
+    otherwise roll back and return a generic 500 error. Note that this does not mean
+    that a request is not allowed to do its own commits in between.
+    """
+
+    async def dispatch(self, request, call_next):
+        if not hasattr(self, "engine"):
+            self.engine = create_engine(
+                settings.connstr,
+                pool_pre_ping=True,
+                echo=settings.sql_debug,
+                poolclass=NullPool if not settings.pooling else None,
+            )
+        response = Response("Internal server error", status_code=500)
+        try:
+            request.state.db = Session(self.engine)
+            response = await call_next(request)
+            request.state.db.commit()
+        except Exception:
+            request.state.db.rollback()
+            raise
+        finally:
+            request.state.db.close()
+        return response
+
+
+def _get_session(request: Request):
+    return request.state.db
+
+
+DBSession = Annotated[Session, Depends(_get_session)]

perfact_api_main-0.2/src/perfact/api/main/perfact_generic.py

@@ -0,0 +1,47 @@
+import base64
+import hashlib
+
+"""
+This file is duplicated code from https://git.perfact.de/DebianPackages/python-perfact/src/branch/master/perfact/generic.py
+
+There is no public available for this code;
+as soon as it exists we can switch to there and
+add the lib as a dependency to this package.
+"""
+
+
+def to_bytes(value, enc="utf-8"):
+    """This method delivers bytes (encoded strings)."""
+    if isinstance(value, memoryview):
+        return value.tobytes()
+    if isinstance(value, bytes):
+        return value
+    if isinstance(value, str):
+        return value.encode(enc)
+    try:
+        return to_bytes(str(value))
+    except Exception:
+        raise ValueError("could not convert '%s' to bytes!" % str((value,)))
+
+
+def secret_check_sha1(encrypted, secret):
+    """Check a secret against its encrypted form.
+
+    >>> secret_check_sha1('{SHA}dYXR9865D9Cxq0LQpso5/PVQZcc=', 'my_secret')
+    True
+    >>> secret_check_sha1(
+    ...    '{SSHA}PtXj4zEBsS0Rxz55sW+USwQizCZy4prJ', 'my_secret')
+    True
+    >>> secret_check_sha1('{SHA}XXXX9865D9Cxq0LQpso5/PVQZcc=', 'my_secret')
+    False
+    """
+    encrypted = to_bytes(encrypted)
+    secret = to_bytes(secret)
+    encoded = encrypted[encrypted.find(b"}") + 1 :]
+    challenge_bytes = base64.urlsafe_b64decode(encoded)
+    digest = challenge_bytes[:20]
+    hr = hashlib.sha1(secret)  # nosec B324
+    if len(challenge_bytes) > 20:
+        salt = challenge_bytes[20:]
+        hr.update(salt)
+    return digest == hr.digest()

perfact_api_main-0.2/src/perfact/api/main/utils.py

@@ -0,0 +1,30 @@
+import logging
+from importlib.metadata import entry_points
+
+from fastapi import FastAPI
+
+
+def discover_add_routes_from_entrypoint(app: FastAPI, entrypoint_group="perfact.api"):
+    """
+    Add all routes discovered for the given entrypoint to the given FastAPI-application
+    """
+    log = logging.getLogger("perfact.api.main.discovery")
+
+    log.info("start plugin discovery")
+    plugin_count = 0
+    for plugin in entry_points(group=entrypoint_group):
+        log.info(f"try to include plugin: {plugin.value}")
+        try:
+            plugin.load()(app)
+            plugin_count += 1
+        except Exception:
+            log.exception(f"failed to include plugin {plugin.value}")
+    log.info(f"finished plugin discovery, included {plugin_count} plugins")
+
+
+def default_logging_settings():
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        datefmt="%Y-%m-%dT%H:%M:%S%z",
+    )

perfact_api_main-0.2/src/perfact_api_main.egg-info/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: perfact-api-main
+Version: 0.2
+Summary: PerFact API - FastAPI main package (middleware, auth, entrypoints)
+Author-email: Viktor Dick <viktor.dick@perfact.de>
+License-Expression: GPL-2.0-or-later
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: SQL
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: argon2-cffi
+Requires-Dist: psycopg[c]
+Requires-Dist: fastapi[standard-no-fastapi-cloud-cli]
+Requires-Dist: sqlalchemy
+Requires-Dist: pydantic-settings
+Requires-Dist: perfact-api-app-model
+
+# PerFact API Base
+The main FastAPI package for the PerFact API. Provides authentication, authorisation, database session handling, and plugin discovery. All domain-specific API modules are in separate packages and loaded automatically at startup via entry points.
+
+## Applications
+
+### `perfact.api.main.app` — user-facing API
+
+Hosts all plugins registered under the `perfact.api` entry point group. Users authenticate via a login cookie or an `Authorization: Apikey …` header. Access to individual endpoints can be restricted by role:
+
+```python
+from perfact.api.main.auth import require_roles
+
+@router.get("/my-endpoint")
+@require_roles("MyRole")
+def my_endpoint(session: DBSession) -> ...:
+    ...
+```
+
+### `perfact.api.main.assignworker` — task runner API
+
+Hosts all plugins registered under the `perfact.assignapi` entry point group. Intended for internal use by `assignd`. Authentication is HTTP Basic Auth with a pre-shared password hash configured in the YAML config file.
+
+## Plugin discovery
+
+At startup, both apps iterate over their respective entry point group and call `mount(app)` on each discovered plugin:
+
+```
+INFO - start plugin discovery
+INFO - try to include plugin: perfact.api.pd.routes:mount
+INFO - finished discovery and include: 1 plugins
+```
+
+A plugin registers itself by declaring an entry point in its `pyproject.toml`:
+
+```toml
+[project.entry-points.'perfact.api']
+myplugin = 'perfact.api.myplugin.routes:mount'
+```
+
+## getting started as developer
+After you checked out this repository, do the following steps to be able to debug your application:
+1. create and activate *venv*
+    ```sh
+    python -m venv .venv
+
+    source .venv/bin/activate # linux
+    .venv/Scripts/Activate.ps1 # PowerShell
+    ```
+1. Install the API plugins you want to include without doing changes by installing them from pypi:
+    ```sh
+    pip install perfact-api-base-model
+    ```
+1. Install the API plugins you want to include and **change** in your instance by checking them out somewhere and installing/linking them into your application via `pip install -e`:
+    ```sh
+    pip install -e ../perfact-api-base-model/ # required
+    pip install -e ../perfact-api-app-model/ # required
+    pip install -e ../perfact-api-pd-model/ # example
+    ```
+
+**Hint**: Every code change is available in the application after the next restart/reload. Changes to the entrypoints are available after the next install command execution (as this is recreating the `ENTRYPOINTS`-file belonging to the package in the site-packages folder).
+
+You can install as much as plugins you like, even custom ones.
+
+*pip* will automaticly check if more dependencies needed by the plugin while installing, e.g.
+```
+Requirement already satisfied: fastapi
+```
+
+
+Now you can run the application:
+```
+uvicorn perfact.api.main.app:app # run API for frontend
+uvicorn perfact.api.main.assignworker:app # run API for assignd worker APIs
+uvicorn perfact.api.main.app:app  --reload --reload-include ../ # run API for frontend with auto-reload for all editable dependencies
+```
+
+There is a `launch.json`-file provided to debug the application in VS Code. To use that, you have to create a configuration file (see below).
+
+## Configuration
+The application can be configured by providing a configuration yaml-File containing informations about the database connection and basic auth credentials (for `assignworker`).
+The configuration file is given to the application by providing the location (absolute or relative to working dir) in the environment variable `PERFACT_API_CONFIG_PATH`.
+
+Example:
+```yaml
+connstr: postgresql+psycopg://zope@/perfactema # default, can be left out
+basicauth: "$argon2id$v=19$m=65536,t=3,p=4$6itEouPTNwWEXDKScKmMrw$NwhN1vAUN8EZjC62HrtXjx7n+K1Mujjd/QqioaHvyOg" # password=test
+```
+
+## Dependencies
+- `perfact-api-app-model`
+- `fastapi`
+- `sqlalchemy`
+- `psycopg[c]`
+- `argon2-cffi`
+- `pydantic-settings`
+
+## Maintainers
+- Viktor Dick <viktor.dick@perfact.de>
+- Alexander Rolfes <alexander.rolfes@perfact.de>

perfact_api_main-0.2/src/perfact_api_main.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+.gitignore
+README.md
+bandit.yml
+pyproject.toml
+tox.ini
+.gitea/workflows/check.yml
+.vscode/launch.json
+.vscode/settings.json
+src/perfact/api/main/__init__.py
+src/perfact/api/main/app.py
+src/perfact/api/main/assignworker.py
+src/perfact/api/main/auth.py
+src/perfact/api/main/config.py
+src/perfact/api/main/dbsession.py
+src/perfact/api/main/perfact_generic.py
+src/perfact/api/main/py.typed
+src/perfact/api/main/utils.py
+src/perfact_api_main.egg-info/PKG-INFO
+src/perfact_api_main.egg-info/SOURCES.txt
+src/perfact_api_main.egg-info/dependency_links.txt
+src/perfact_api_main.egg-info/requires.txt
+src/perfact_api_main.egg-info/top_level.txt

perfact_api_main-0.2/src/perfact_api_main.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

perfact_api_main-0.2/src/perfact_api_main.egg-info/requires.txt

@@ -0,0 +1,6 @@
+argon2-cffi
+psycopg[c]
+fastapi[standard-no-fastapi-cloud-cli]
+sqlalchemy
+pydantic-settings
+perfact-api-app-model

perfact_api_main-0.2/src/perfact_api_main.egg-info/top_level.txt

@@ -0,0 +1 @@
+perfact

perfact_api_main-0.2/tox.ini

@@ -0,0 +1,32 @@
+[tox]
+envlist = py3
+isolated_build = true
+
+[pytest]
+
+[testenv]
+passenv = SSH_AUTH_SOCK, PYTHONPATH, HTTP_PROXY, HTTPS_PROXY
+setenv =
+    GIT_SSH_VARIANT=ssh
+    GIT_SSH_COMMAND=ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no
+
+deps =
+    ruff
+    pytest
+    coverage
+    psycopg[c]
+    pytest-postgresql
+    pytest-cov
+    pytest-typing
+    bandit
+    mypy
+    types-pyyaml
+    perfact-api-base-model @ git+ssh://git@git.perfact.de:3022/PythonPackages/perfact-api-base-model
+    perfact-api-app-model @ git+ssh://git@git.perfact.de:3022/PythonPackages/perfact-api-app-model
+
+commands =
+    ruff format --check
+    ruff check
+    bandit --configfile bandit.yml -r src
+    mypy src
+    # pytest --doctest-modules --cov-branch --cov=src --cov-report=term-missing {posargs:src}