basic-python-project 0.0.0__py3-none-any.whl

basic_python_project-0.0.0.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: basic-python-project
+Version: 0.0.0
+Summary: Template: Basic Python Project
+Author-email: Christian Hänig <christian.haenig@hs-anhalt.de>
+Project-URL: Gitlab, https://gitlab.hs-anhalt.de/ki/templates/basic-python-project
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown; charset=UTF-8
+License-File: LICENSE
+Requires-Dist: fastapi~=0.115.5
+Requires-Dist: pytest~=8.3
+Requires-Dist: pytest-asyncio~=0.24
+Requires-Dist: starlette~=0.41.3
+Requires-Dist: uvicorn~=0.32.1
+Requires-Dist: python-keycloak~=4.7.3
+Requires-Dist: python-dotenv~=1.0.1
+Requires-Dist: sqlmodel~=0.0.34
+Requires-Dist: sqlalchemy~=2.0
+Requires-Dist: asyncpg~=0.30.0
+Requires-Dist: geoalchemy2~=0.15.2
+Requires-Dist: minio~=7.2
+Requires-Dist: Pillow~=11.0
+Requires-Dist: python-multipart~=0.0.20
+Requires-Dist: sentry-sdk[fastapi]~=2.0
+Dynamic: license-file
+
+# Meinewaldki Citizen Rest Service
+
+
+## Installation for Kubernetes
+
+You need to have helm and kubectl installed.
+
+Your kubeconfig should be set to the correct cluster (meinewaldki).
+
+```bash
+kubectl config current-context
+```
+
+Navigate to the configuration directory:
+
+```bash
+cd config
+```
+
+### Keycloak
+
+For keycloak you need to run the following command:
+
+```bash
+helm install test-keycloak keycloak --namespace citizen-scientist-app
+```
+
+The configurations are in the keycloak/values.yaml file.
+
+Base configuration your endpoint will be `https://meinewaldki.anhalt.ai/dev-auth`.
+
+To uninstall keycloak run the following command:
+
+```bash
+helm uninstall test-keycloak --namespace citizen-scientist-app
+```
+
+#### Settings
+
+Log into keycloak with the following credentials:
+
+```
+Username: admin-dev
+Password: PLS_CHG_ME
+```
+
+Add a new realm for guest users.
+
+In the new realm create a new client with the ClientID `MeineWaldKIApp`.
+Enable OAuth 2.0 Device Authorization Grant.
+
+After creating the client change the following settings:
+
+Origin: `*` (should be more restrictive in production, but did not check if this works with a more restrictive setting)
+Valid Redirect URIs: `*` (should be more restrictive in production, but did not check if this works with a more restrictive setting)
+
+Add the role `guest` to the client roles.
+
+Go to Realm Settings. Set SSO Session Idle very high and SSO Session also very high (Sessions).
+
+Set Access Token Lifespan to a very high value (Tokens).
+
+Remove the first name and last name from the required user attributes (User profile).
+
+
+### Installation Rest Service
+
+I will add the automatic deployment through CI/CD later.
+
+The deployment helm is mostly written but the Docker image is not yet in a registry.
+
+
+## Run locally
+After Installing keycloak and creating your realms and changing the admin password and or admin user you can run the service locally.
+
+Add the following environment variables to your .env file:
+
+```env
+KEYCLOAK_SERVER_URL=https://meinewaldki.anhalt.ai/dev-auth/ (if not changed)
+ADMIN_USERNAME=admin_dev (if not changed)
+ADMIN_PASSWORD=PLS_CHG_ME (if not changed)
+ADMIN_REALM_NAME=master (if not changed)
+GUEST_USER_REALM_NAME=YourRealm (I set it to guest-users)
+```
+
+Mark the src directory as source root in your IDE.
+
+Run the main.py file with the working directory set to the root directory of the project.
+
+### Endpoints
+I did not setup an endpoint for cookies. This should make it easier to test the endpoints.
+
+http://127.0.0.1:5001/citizen-api/guest-user/create -> Create a new guest user
+http://127.0.0.1:5001/citizen-api/guest-user/check -> Check if Token is valid (Post request)
+http://127.0.0.1:5001/citizen-api/docs -> Swagger UI (Easy to test the endpoints)

basic_python_project-0.0.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+basic_python_project-0.0.0.dist-info/licenses/LICENSE,sha256=5acGOP9i5gEE-QIwcpnp4V8yQn-VfGJEgausFBegr3M,1065
+meinewaldki_citizen_rest_service/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+meinewaldki_citizen_rest_service/constants.py,sha256=Afv9zNuB-D1eyr1UgMqzbhHjcSPzstBcQWBUC7bo5BU,1883
+meinewaldki_citizen_rest_service/dependencies.py,sha256=fkAbNY-Pv10YbXmRMnw58kFxXCSxBQUdgpCIXQVXRlk,3786
+meinewaldki_citizen_rest_service/keycloak_clients.py,sha256=9r0l7cR5Ayhn5cfxM07Oo-OwbJU0PJeBz0Ma2Nh3m0Y,1658
+meinewaldki_citizen_rest_service/main.py,sha256=pyUACl3_0XTl4spkFkVIlXt5deLecswBkJnzwPYbu30,2143
+meinewaldki_citizen_rest_service/minio_client.py,sha256=dVccSyHyWHX-2UKSIkpBcrIlTjiTHQJwbkNrzlfe4MI,1165
+meinewaldki_citizen_rest_service/database/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+meinewaldki_citizen_rest_service/database/engine.py,sha256=IqvRIjWMUkt7O0ZVH2ZBx5eyhu6LxfYDW_3nl8AKLnw,999
+meinewaldki_citizen_rest_service/database/models.py,sha256=jzdDmFmg-_HmYmRIO7nEUL8eTZHGWxOnFmURCgWjZqw,8137
+meinewaldki_citizen_rest_service/routers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+meinewaldki_citizen_rest_service/routers/guest_user_access.py,sha256=uYUPCXGJzYcRAmTBqviVvLAovSCI_yeDn9J01TwCNf0,1071
+meinewaldki_citizen_rest_service/routers/records.py,sha256=P7NOxQACrpvr5pP1bZHniwdJTy6IlE7mVR1Iu-V0GzU,9185
+meinewaldki_citizen_rest_service/routers/users.py,sha256=cydYSG-S5WkbCcFIp_GGVBVpaTZlgUXJUU50pjjoT1s,3153
+meinewaldki_citizen_rest_service/schemas/__init__.py,sha256=7xpv5aDmPtSKvV4onttFeoBwuCCE3I3lJjvlq8G9FqM,1044
+meinewaldki_citizen_rest_service/schemas/citizen_science.py,sha256=l8fpSFquoZIjNv-LlJAJ1O2tfeTiN7rQ2B_ktT51Xq0,1492
+meinewaldki_citizen_rest_service/schemas/image.py,sha256=50g0cMPIPRExKrPrDZeHKsuRI7w_y-LZsAmKKU8aG-I,1253
+meinewaldki_citizen_rest_service/schemas/record.py,sha256=RGGi8m525IYOmndAB4ehDDlvdGQbcS21TcLwVUNtOYg,1559
+meinewaldki_citizen_rest_service/schemas/user.py,sha256=aoJisftU6KO_LqdVOCkfD6Sise_URj75l9GOq6RcOKU,588
+basic_python_project-0.0.0.dist-info/METADATA,sha256=6hHJscVGS6Nwg0_QYu3w36D5AhrHB012nAx_or4HjEc,3756
+basic_python_project-0.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+basic_python_project-0.0.0.dist-info/top_level.txt,sha256=jaOy8r_p7Vzk7IrDSiAsVvgaU_TJ0kVMdB7SBC4qwvI,33
+basic_python_project-0.0.0.dist-info/RECORD,,

basic_python_project-0.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

basic_python_project-0.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AnhaltAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

basic_python_project-0.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+meinewaldki_citizen_rest_service

meinewaldki_citizen_rest_service/constants.py

@@ -0,0 +1,55 @@
+"""Constants for the MeineWaldKI Citizen REST Service."""
+
+import os
+
+from dotenv import load_dotenv
+
+if os.path.exists(".env"):
+    load_dotenv(dotenv_path=".env")
+
+KEYCLOAK_SERVER_URL = os.environ["KEYCLOAK_SERVER_URL"]
+# Optional path to a CA cert for Keycloak TLS verification.
+# Set in dev when using a self-signed cert. Leave unset in production.
+KEYCLOAK_CERT_PATH = os.environ.get("KEYCLOAK_CERT_PATH")
+
+GUEST_ADMIN_USERNAME = os.environ["GUEST_ADMIN_USERNAME"]
+GUEST_ADMIN_PASSWORD = os.environ["GUEST_ADMIN_PASSWORD"]
+GUEST_ADMIN_REALM_NAME = os.environ["GUEST_ADMIN_REALM_NAME"]
+
+REGISTERED_ADMIN_USERNAME = os.environ["REGISTERED_ADMIN_USERNAME"]
+REGISTERED_ADMIN_PASSWORD = os.environ["REGISTERED_ADMIN_PASSWORD"]
+REGISTERED_ADMIN_REALM_NAME = os.environ["REGISTERED_ADMIN_REALM_NAME"]
+
+GUEST_USER_REALM_NAME = os.environ["GUEST_USER_REALM_NAME"]
+REGISTERED_USER_REALM_NAME = os.environ["REGISTERED_USER_REALM_NAME"]
+
+CLIENT_NAME = "MeineWaldKIApp"
+
+DB_USER = os.environ.get("DB_USER", "")
+DB_PASSWORD = os.environ.get("DB_PASSWORD", "")
+DB_HOST = os.environ.get("DB_HOST", "")
+DB_PORT = os.environ.get("DB_PORT", "5432")
+DB_NAME = os.environ.get("DB_NAME", "")
+
+MINIO_ENDPOINT = os.environ["MINIO_ENDPOINT"]
+MINIO_ACCESS_KEY = os.environ["MINIO_ACCESS_KEY"]
+MINIO_SECRET_KEY = os.environ["MINIO_SECRET_KEY"]
+MINIO_BUCKET = os.environ["MINIO_BUCKET"]
+MINIO_SECURE = os.environ.get("MINIO_SECURE", "true").lower() == "true"
+
+# GlitchTip / Sentry DSN — leave unset to disable error reporting
+GLITCHTIP_DSN = os.environ.get("GLITCHTIP_DSN")
+
+# EPSG:4326 — World Geodetic System 1984. Lat/lon in decimal degrees on the
+# WGS 84 ellipsoid; the reference system behind GPS and most web maps.
+WGS84_SRID = 4326
+
+ALLOWED_IMAGE_MIME_TYPES = frozenset(
+    {
+        "image/jpeg",
+        "image/png",
+        "image/webp",
+        "image/heic",
+        "image/heif",
+    }
+)

meinewaldki_citizen_rest_service/database/engine.py

@@ -0,0 +1,35 @@
+from collections.abc import AsyncGenerator
+from urllib.parse import quote_plus
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+from meinewaldki_citizen_rest_service.constants import (
+    DB_HOST,
+    DB_NAME,
+    DB_PASSWORD,
+    DB_PORT,
+    DB_USER,
+)
+
+_DATABASE_URL = (
+    f"postgresql+asyncpg://{quote_plus(DB_USER)}"
+    f":{quote_plus(DB_PASSWORD)}@{DB_HOST}:{DB_PORT}/{DB_NAME}"
+)
+
+engine = create_async_engine(_DATABASE_URL, echo=False, pool_pre_ping=True)
+
+SessionLocal = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    """Yields an async database session for use as a FastAPI dependency.
+
+    Yields:
+        An async SQLAlchemy session that is automatically rolled back on error.
+    """
+    async with SessionLocal() as session:
+        try:
+            yield session
+        except Exception:
+            await session.rollback()
+            raise

meinewaldki_citizen_rest_service/database/models.py

@@ -0,0 +1,276 @@
+"""SQLModel ORM table models for the MeineWaldKI citizen science database.
+
+Each table model inherits from the corresponding base in schemas/ and adds:
+- primary / foreign keys
+- server-managed fields (uploaded_at, is_anonymized, sync_status)
+- PostgreSQL-specific column types: schema-qualified SAEnum, JSONB, Geography.
+  These override the Python-native base-class fields via sa_column so that the
+  DB schema is mirrored exactly while the base remains Pydantic-compatible.
+"""
+
+import uuid
+from datetime import UTC, datetime
+from typing import Any, Optional
+
+from geoalchemy2 import Geography
+from sqlalchemy import (
+    Column,
+    DateTime,
+    Enum as SAEnum,
+    Identity,
+    Integer,
+    UniqueConstraint,
+)
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlmodel import Field
+
+from meinewaldki_citizen_rest_service.constants import WGS84_SRID
+from meinewaldki_citizen_rest_service.schemas import (
+    CitizenScienceFeatureBase,
+    CitizenScienceFeatureOptionBase,
+    CitizenScienceUserAssignmentBase,
+    CsAssignmentSource,
+    CsAssignmentType,
+    CsValueType,
+    ImageBase,
+    ImageOrientation,
+    ImageSyncStatus,
+    RecordBase,
+    RecordSyncStatus,
+    UserBase,
+    UserStatus,
+)
+
+
+class User(UserBase, table=True):
+    """Maps to core.users."""
+
+    __tablename__ = "users"
+    __table_args__ = {"schema": "core"}
+
+    id: uuid.UUID = Field(primary_key=True)
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        sa_column=Column(DateTime(timezone=True), nullable=False),
+    )
+
+    # Override: reference the existing core.user_status enum type
+    status: UserStatus = Field(
+        sa_column=Column(
+            SAEnum(UserStatus, name="user_status", schema="core", create_type=False),
+            nullable=False,
+            server_default="guest",
+        )
+    )
+
+
+class Record(RecordBase, table=True):
+    """Maps to core.records."""
+
+    __tablename__ = "records"
+    __table_args__ = (
+        UniqueConstraint(
+            "client_record_id",
+            "user_id",
+            "created_at",
+            name="uq_record_client_user_created",
+        ),
+        {"schema": "core"},
+    )
+
+    # GENERATED BY DEFAULT AS IDENTITY in the DB
+    id: Optional[int] = Field(
+        default=None,
+        sa_column=Column(Integer, Identity(always=False), primary_key=True),
+    )
+
+    user_id: uuid.UUID = Field(foreign_key="core.users.id", nullable=False)
+
+    created_at: datetime = Field(
+        sa_column=Column(DateTime(timezone=True), nullable=False),
+    )
+
+    uploaded_at: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        sa_column=Column(DateTime(timezone=True), nullable=False),
+    )
+
+    original_location: Optional[Any] = Field(
+        default=None,
+        sa_column=Column(
+            Geography(geometry_type="POINT", srid=WGS84_SRID), nullable=True
+        ),
+    )
+    updated_location: Optional[Any] = Field(
+        default=None,
+        sa_column=Column(
+            Geography(geometry_type="POINT", srid=WGS84_SRID), nullable=True
+        ),
+    )
+
+    is_anonymized: bool = Field(default=False)
+    sync_status: RecordSyncStatus = Field(
+        sa_column=Column(
+            SAEnum(
+                RecordSyncStatus,
+                name="record_sync_status",
+                schema="core",
+                create_type=False,
+            ),
+            nullable=False,
+            server_default="pending",
+        )
+    )
+
+    # Override: use JSONB instead of plain JSON
+    hardware_data: Optional[dict] = Field(
+        default=None, sa_column=Column(JSONB, nullable=True)
+    )
+
+
+class Image(ImageBase, table=True):
+    """Maps to core.images."""
+
+    __tablename__ = "images"
+    __table_args__ = (
+        UniqueConstraint(
+            "record_id",
+            "image_orientation",
+            name="uq_images_record_orientation",
+        ),
+        {"schema": "core"},
+    )
+
+    # GENERATED BY DEFAULT AS IDENTITY in the DB
+    id: Optional[int] = Field(
+        default=None,
+        sa_column=Column(Integer, Identity(always=False), primary_key=True),
+    )
+
+    record_id: int = Field(foreign_key="core.records.id", nullable=False)
+
+    minio_path: Optional[str] = Field(default=None, nullable=True)
+
+    uploaded_at: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        sa_column=Column(DateTime(timezone=True), nullable=False),
+    )
+    is_anonymized: bool = Field(default=False)
+    sync_status: ImageSyncStatus = Field(
+        sa_column=Column(
+            SAEnum(
+                ImageSyncStatus,
+                name="image_sync_status",
+                schema="core",
+                create_type=False,
+            ),
+            nullable=False,
+            server_default="pending",
+        )
+    )
+
+    # Override: reference the existing core.image_orientation enum type
+    image_orientation: ImageOrientation = Field(
+        sa_column=Column(
+            SAEnum(
+                ImageOrientation,
+                name="image_orientation",
+                schema="core",
+                create_type=False,
+            ),
+            nullable=False,
+        )
+    )
+
+    # Override: use JSONB instead of plain JSON
+    exif_metadata: Optional[dict] = Field(
+        default=None, sa_column=Column(JSONB, nullable=True)
+    )
+
+
+class CitizenScienceFeature(CitizenScienceFeatureBase, table=True):
+    """Maps to core.citizen_science_features."""
+
+    __tablename__ = "citizen_science_features"
+    __table_args__ = {"schema": "core"}
+
+    # GENERATED BY DEFAULT AS IDENTITY in the DB
+    id: Optional[int] = Field(
+        default=None,
+        sa_column=Column(Integer, Identity(always=False), primary_key=True),
+    )
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        sa_column=Column(DateTime(timezone=True), nullable=False),
+    )
+
+    # Override: reference existing core enum types
+    value_type: CsValueType = Field(
+        sa_column=Column(
+            SAEnum(CsValueType, name="cs_value_type", schema="core", create_type=False),
+            nullable=False,
+        )
+    )
+    assignment_type: CsAssignmentType = Field(
+        sa_column=Column(
+            SAEnum(
+                CsAssignmentType,
+                name="cs_assignment_type",
+                schema="core",
+                create_type=False,
+            ),
+            nullable=False,
+        )
+    )
+
+
+class CitizenScienceFeatureOption(CitizenScienceFeatureOptionBase, table=True):
+    """Maps to core.citizen_science_feature_options."""
+
+    __tablename__ = "citizen_science_feature_options"
+    __table_args__ = (
+        UniqueConstraint("feature_id", "feature_value", name="uq_feature_value"),
+        {"schema": "core"},
+    )
+
+    # GENERATED BY DEFAULT AS IDENTITY in the DB
+    id: Optional[int] = Field(
+        default=None,
+        sa_column=Column(Integer, Identity(always=False), primary_key=True),
+    )
+    feature_id: int = Field(
+        foreign_key="core.citizen_science_features.id", nullable=False
+    )
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        sa_column=Column(DateTime(timezone=True), nullable=False),
+    )
+
+
+class CitizenScienceUserAssignment(CitizenScienceUserAssignmentBase, table=True):
+    """Maps to core.citizen_science_user_assignments."""
+
+    __tablename__ = "citizen_science_user_assignments"
+    __table_args__ = {"schema": "core"}
+
+    user_id: uuid.UUID = Field(primary_key=True, foreign_key="core.users.id")
+    option_id: int = Field(
+        primary_key=True, foreign_key="core.citizen_science_feature_options.id"
+    )
+    assigned_at: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        sa_column=Column(DateTime(timezone=True), nullable=False),
+    )
+
+    # Override: reference the existing core.cs_assignment_source enum type
+    source: CsAssignmentSource = Field(
+        sa_column=Column(
+            SAEnum(
+                CsAssignmentSource,
+                name="cs_assignment_source",
+                schema="core",
+                create_type=False,
+            ),
+            nullable=False,
+        )
+    )

meinewaldki_citizen_rest_service/dependencies.py

@@ -0,0 +1,133 @@
+"""Reusable FastAPI dependencies."""
+
+import base64
+import json
+import uuid
+from dataclasses import dataclass
+from typing import Annotated, Optional
+
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from keycloak import KeycloakAdmin
+
+from meinewaldki_citizen_rest_service.constants import (
+    GUEST_USER_REALM_NAME,
+    REGISTERED_USER_REALM_NAME,
+)
+from meinewaldki_citizen_rest_service.keycloak_clients import (
+    guest_user_admin,
+    guest_user_client,
+    registered_user_admin,
+    registered_user_client,
+)
+from meinewaldki_citizen_rest_service.schemas import UserStatus
+
+_bearer = HTTPBearer()
+
+_UNAUTHORIZED = HTTPException(
+    status_code=status.HTTP_401_UNAUTHORIZED,
+    detail="Invalid or expired access token",
+    headers={"WWW-Authenticate": "Bearer"},
+)
+
+
+@dataclass
+class TokenData:
+    user_id: uuid.UUID
+    user_type: UserStatus
+    email: Optional[str]
+
+
+def _realm_from_token(token: str) -> str:
+    """Extracts the realm name from the JWT iss claim without verifying the signature.
+
+    Keycloak sets iss to: ``{server_url}/realms/{realm_name}``.
+
+    Args:
+        token: Raw JWT bearer token string.
+
+    Returns:
+        The Keycloak realm name extracted from the ``iss`` claim.
+
+    Raises:
+        HTTPException: If the token cannot be decoded or lacks an ``iss`` claim.
+    """
+    try:
+        payload_b64 = token.split(".")[1]
+        payload_b64 += "=" * (4 - len(payload_b64) % 4)
+        payload = json.loads(base64.b64decode(payload_b64))
+        return payload["iss"].rstrip("/").split("/")[-1]
+    except Exception:
+        raise _UNAUTHORIZED
+
+
+def get_current_user_id(
+    credentials: Annotated[HTTPAuthorizationCredentials, Depends(_bearer)],
+) -> uuid.UUID:
+    """Verifies the bearer token against the correct Keycloak realm.
+
+    Args:
+        credentials: HTTP Bearer credentials from the Authorization header.
+
+    Returns:
+        The authenticated user's UUID.
+
+    Raises:
+        HTTPException: If the token is invalid or the realm is unrecognised.
+    """
+    token = credentials.credentials
+    realm = _realm_from_token(token)
+
+    if realm == GUEST_USER_REALM_NAME:
+        client = guest_user_client
+    elif realm == REGISTERED_USER_REALM_NAME:
+        client = registered_user_client
+    else:
+        raise _UNAUTHORIZED
+
+    try:
+        user_info = client.decode_token(token)
+        return uuid.UUID(user_info["sub"])
+    except Exception:
+        raise _UNAUTHORIZED
+
+
+def get_current_token_data(
+    credentials: Annotated[HTTPAuthorizationCredentials, Depends(_bearer)],
+) -> TokenData:
+    """Verify the bearer token and return the user ID, user type, and email."""
+    token = credentials.credentials
+    realm = _realm_from_token(token)
+
+    if realm == GUEST_USER_REALM_NAME:
+        client = guest_user_client
+        user_type = UserStatus.guest
+    elif realm == REGISTERED_USER_REALM_NAME:
+        client = registered_user_client
+        user_type = UserStatus.registered
+    else:
+        raise _UNAUTHORIZED
+
+    try:
+        user_info = client.decode_token(token)
+        return TokenData(
+            user_id=uuid.UUID(user_info["sub"]),
+            user_type=user_type,
+            email=user_info.get("email"),
+        )
+    except Exception:
+        raise _UNAUTHORIZED
+
+
+def get_current_keycloak_admin(
+    credentials: Annotated[HTTPAuthorizationCredentials, Depends(_bearer)],
+) -> KeycloakAdmin:
+    """Return the Keycloak admin client for the realm that issued the token."""
+    realm = _realm_from_token(credentials.credentials)
+
+    if realm == GUEST_USER_REALM_NAME:
+        return guest_user_admin
+    elif realm == REGISTERED_USER_REALM_NAME:
+        return registered_user_admin
+    else:
+        raise _UNAUTHORIZED