endoreg-db 0.8.9.32__py3-none-any.whl

endoreg_db/authz/policy.py

@@ -0,0 +1,224 @@
+"""
+Authorization policy for DRF routes, backed by Keycloak realm roles.
+
+Concepts
+========
+
+- Keycloak holds *roles* (realm roles) like "patient:read", "patient:write",
+  "video:read", "video:write", "admin", etc.
+- At login, those roles are synced to Django Groups with the *same* names.
+- This file defines how DRF *routes* map to those roles.
+
+Goals
+=====
+
+1) Be DYNAMIC:
+   - By default, we assume:
+       GET/HEAD/OPTIONS → "<resource>:read"
+       POST/PUT/PATCH/DELETE → "<resource>:write"
+   - You only override special cases.
+
+2) Be EXPLICIT where needed:
+   - Some routes may require a specific role (e.g. "admin").
+
+3) Keep the “write ⇒ read” convention:
+   - If a user has "patient:write", they automatically satisfy "patient:read".
+"""
+
+from typing import Dict, Union
+
+# ------------------------------------------------------------
+# Types
+# ------------------------------------------------------------
+
+# A route can map to:
+#   - a single role string ("patient:read")
+#   - or per-method roles: {"GET": "patient:read", "POST": "patient:write", ...}
+RouteRoles = Dict[str, Union[str, Dict[str, str]]]
+
+# ------------------------------------------------------------
+# Resource → roles (technical roles in Keycloak)
+# ------------------------------------------------------------
+# These are the "technical" roles you create in Keycloak
+# and assign to users/groups (directly or via composite roles).
+#
+# For each resource, define which role is used for read & write.
+RESOURCE_ROLES = {
+    "patient": {
+        "read": "patient:read",
+        "write": "patient:write",
+    },
+    "video": {
+        "read": "video:read",
+        "write": "video:write",
+    },
+    # anonymization resource
+    "anonymization": {
+        "read": "anonymization:read",
+        "write": "anonymization:write",
+    },
+    # Add more resources as needed:
+    # "report": {"read": "report:read", "write": "report:write"},
+}
+
+# ------------------------------------------------------------
+# Route → resource mapping
+# ------------------------------------------------------------
+# Map DRF route names to a resource key above.
+#
+# Route names:
+#   - ViewSet via DefaultRouter:
+#       basename="patient"  → "patient-list", "patient-detail"
+#   - @action on a ViewSet:
+#       "<basename>-<action_name>"
+#   - path(..., name="..."):
+#       exactly that "name"
+ROUTE_RESOURCE = {
+    # Patients
+    "patient-list": "patient",  # /api/patients/
+    "patient-detail": "patient",  # /api/patients/{id}/
+    # Custom patient helper
+    "check_pe_exist": "patient",
+    # Example for videos (if you have these ViewSets registered)
+    "videos-list": "video",
+    "videos-detail": "video",
+    # Media video endpoints
+    "video-list": "video",
+    "video-detail": "video",
+    "video-detail-stream": "video",
+    "video-stream": "video",
+    "video-reimport": "video",
+    "video-correction": "video",
+    "video-metadata": "video",
+    "video-apply-mask": "video",
+    "video-remove-frames": "video",
+    "get_lvs_list": "video",
+    "anonymization_items_overview": "anonymization",
+    # Add more mappings as your API grows
+}
+
+# ------------------------------------------------------------
+# Explicit overrides by route
+# ------------------------------------------------------------
+# ONLY put something here if it deviates from the normal pattern.
+#
+# Example use cases:
+#   - admin-only DELETE
+#   - public GET that doesn't require login
+#
+# If a route is NOT in REQUIRED_ROLES, the policy falls back to:
+#   1) ROUTE_RESOURCE + RESOURCE_ROLES
+#   2) DEFAULT_ROLE_BY_METHOD
+REQUIRED_ROLES: RouteRoles = {
+    # Example: make patient DELETE admin-only (optional)
+    # "patient-detail": {
+    #     "DELETE": "admin",  # admin role in Keycloak
+    # },
+    # Example: a special helper route that you always want read-only patients role:
+    # "check_pe_exist": "patient:read",
+}
+
+# ------------------------------------------------------------
+# Fallback by HTTP method (used when no per-route override)
+# ------------------------------------------------------------
+# This is the last fallback if a route is not in REQUIRED_ROLES
+# *and* not in ROUTE_RESOURCE.
+#
+# If you want global "data:read"/"data:write" roles to stay valid,
+# you can leave this as "data:read"/"data:write".
+#
+# If you move fully to resource-based roles, you can leave this as None
+# or a generic "data:read"/"data:write" depending on your preference.
+DEFAULT_ROLE_BY_METHOD = {
+    "GET": "data:read",
+    "HEAD": "data:read",
+    "OPTIONS": "data:read",
+    "POST": "data:write",
+    "PUT": "data:write",
+    "PATCH": "data:write",
+    "DELETE": "data:write",
+}
+
+
+# ------------------------------------------------------------
+# Role satisfaction rule
+# ------------------------------------------------------------
+
+
+def satisfies(user_roles: set[str], needed: str) -> bool:
+    """
+    Return True if user_roles satisfy the needed role.
+
+    Rules:
+      - Exact match → allow
+      - "write ⇒ read":
+          If needed ends with ':read', having '<base>:write' also counts.
+
+    Examples:
+      user_roles = {"patient:read"}:
+        satisfies(..., "patient:read")  → True
+        satisfies(..., "patient:write") → False
+
+      user_roles = {"patient:write"}:
+        satisfies(..., "patient:write") → True
+        satisfies(..., "patient:read")  → True (write ⇒ read)
+    """
+    if not needed:
+        return False
+
+    #  Global override: any user with role "endoregdb_user" passes all checks
+    if "endoregdb_user" in user_roles:
+        return True
+
+    # 1) exact role match
+    if needed in user_roles:
+        return True
+
+    # 2) write⇒read shortcut
+    if needed.endswith(":read"):
+        base = needed.rsplit(":", 1)[0]
+        if f"{base}:write" in user_roles:
+            return True
+
+    return False
+
+
+# ------------------------------------------------------------
+# Helper: compute which role is needed for a given route + method
+# ------------------------------------------------------------
+
+
+def get_needed_role(route_name: str, method: str) -> str | None:
+    """
+    Compute the required role for a given route + HTTP method.
+
+    Priority:
+      1) REQUIRED_ROLES[route_name] if present
+         - if dict: use per-method role if defined
+         - if str : use that role for all methods
+      2) ROUTE_RESOURCE + RESOURCE_ROLES (resource-based policy)
+         - e.g. route "patient-list" with GET → "patient:read"
+      3) DEFAULT_ROLE_BY_METHOD[method] as final fallback
+         - e.g. "data:read"/"data:write" if you keep those as global roles.
+    """
+    method = (method or "").upper()
+
+    # 1) explicit per-route overrides
+    per_route = REQUIRED_ROLES.get(route_name)
+    if isinstance(per_route, dict):
+        role = per_route.get(method)
+        if role:
+            return role
+    elif isinstance(per_route, str):
+        return per_route  # one role for all methods of that route
+
+    # 2) resource-based default
+    resource = ROUTE_RESOURCE.get(route_name)
+    if resource in RESOURCE_ROLES:
+        op = "read" if method in ("GET", "HEAD", "OPTIONS") else "write"
+        role = RESOURCE_ROLES[resource].get(op)
+        if role:
+            return role
+
+    # 3) global fallback by method
+    return DEFAULT_ROLE_BY_METHOD.get(method)

endoreg_db/authz/settings.py

@@ -0,0 +1,64 @@
+from django.conf import settings
+
+from endoreg_db.config.settings import keycloak as keycloak_settings
+
+
+def _get_setting(name):
+    if hasattr(settings, name):
+        return getattr(settings, name)
+    return None
+
+
+def _set_if_missing(name, value):
+    if value is None:
+        return
+    if isinstance(value, str) and not value:
+        return
+    current = _get_setting(name)
+    if current is None:
+        setattr(settings, name, value)
+        return
+    if isinstance(current, str) and not current:
+        setattr(settings, name, value)
+
+
+def ensure_keycloak_settings():
+    """
+    Ensure Keycloak-related settings exist for mozilla-django-oidc and JWT auth.
+    This only fills in missing values and never overrides explicit settings.
+    """
+    _set_if_missing("KEYCLOAK_BASE_URL", keycloak_settings.KEYCLOAK_BASE_URL)
+    _set_if_missing("KEYCLOAK_REALM", keycloak_settings.KEYCLOAK_REALM)
+
+    _set_if_missing("OIDC_RP_CLIENT_ID", keycloak_settings.OIDC_RP_CLIENT_ID)
+    _set_if_missing("OIDC_RP_CLIENT_SECRET", keycloak_settings.OIDC_RP_CLIENT_SECRET)
+
+    _set_if_missing(
+        "OIDC_OP_DISCOVERY_ENDPOINT",
+        keycloak_settings.OIDC_OP_DISCOVERY_ENDPOINT,
+    )
+    _set_if_missing(
+        "OIDC_OP_AUTHORIZATION_ENDPOINT",
+        keycloak_settings.OIDC_OP_AUTHORIZATION_ENDPOINT,
+    )
+    _set_if_missing("OIDC_OP_TOKEN_ENDPOINT", keycloak_settings.OIDC_OP_TOKEN_ENDPOINT)
+    _set_if_missing("OIDC_OP_USER_ENDPOINT", keycloak_settings.OIDC_OP_USER_ENDPOINT)
+    _set_if_missing("OIDC_OP_JWKS_ENDPOINT", keycloak_settings.OIDC_OP_JWKS_ENDPOINT)
+
+    _set_if_missing(
+        "OIDC_OP_LOGOUT_ENDPOINT",
+        keycloak_settings.OIDC_OP_LOGOUT_ENDPOINT,
+    )
+    _set_if_missing("OIDC_STORE_ID_TOKEN", keycloak_settings.OIDC_STORE_ID_TOKEN)
+    _set_if_missing(
+        "OIDC_LOGOUT_REDIRECT_URL",
+        keycloak_settings.OIDC_LOGOUT_REDIRECT_URL,
+    )
+
+    _set_if_missing("OIDC_RP_SCOPES", keycloak_settings.OIDC_RP_SCOPES)
+    _set_if_missing("OIDC_RP_SIGN_ALGO", keycloak_settings.OIDC_RP_SIGN_ALGO)
+    _set_if_missing("OIDC_VERIFY_SSL", keycloak_settings.OIDC_VERIFY_SSL)
+
+    _set_if_missing("LOGIN_URL", keycloak_settings.LOGIN_URL)
+    _set_if_missing("LOGIN_REDIRECT_URL", keycloak_settings.LOGIN_REDIRECT_URL)
+    _set_if_missing("LOGOUT_REDIRECT_URL", keycloak_settings.LOGOUT_REDIRECT_URL)

endoreg_db/authz/views_auth.py

@@ -0,0 +1,70 @@
+# libs/endoreg-db/endoreg_db/authz/views_auth.py
+
+from rest_framework.decorators import api_view, permission_classes
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.response import Response
+
+from .policy import satisfies, get_needed_role
+
+# Map frontend page keys → (DRF route name, HTTP method)
+#
+# Route names come from your router registration, e.g.:
+#   router.register(r'patients', PatientViewSet, basename='patient')
+# => "patient-list", "patient-detail"
+PAGE_CAPS = {
+    # Vue route /patienten
+    "page.patients.view": ("patient-list", "GET"),
+    # You can extend later, e.g.:
+    # "page.reports.view": ("report-list", "GET"),
+    # "page.anonymization.view": ("anonymization-list", "GET"),
+}
+
+
+@api_view(["GET"])
+@permission_classes([IsAuthenticated])
+def auth_bootstrap(request):
+    """
+    Return auth context for the frontend:
+      - current user (username, basic info)
+      - roles (Django groups, synced from Keycloak)
+      - capabilities (what parts of UI the user may access)
+    """
+    user = request.user
+
+    # Roles = Django group names = Keycloak roles synced from Keycloak
+    roles = set(user.groups.values_list("name", flat=True))
+
+    capabilities = {}
+
+    for cap_key, (route_name, method) in PAGE_CAPS.items():
+        method = method.upper()
+
+        # Look up which role is needed for this route/method
+        # needed = REQUIRED_ROLES.get(route_name) or DEFAULT_ROLE_BY_METHOD.get(method)
+        needed = get_needed_role(route_name, method)
+
+        if not needed:
+            # No role mapping defined → secure default: deny
+            capabilities[cap_key] = {"read": False, "write": False}
+            continue
+
+        allowed = satisfies(
+            roles, needed
+        )  # uses your existing rule: write ⇒ read, etc.
+
+        # For UI pages we usually only care about "read"
+        capabilities[cap_key] = {
+            "read": bool(allowed),
+            "write": False,  # or bool(allowed) if this page allows writes in UI
+        }
+
+    return Response(
+        {
+            "user": {
+                "username": user.username,
+                "roles": sorted(roles),
+            },
+            "roles": sorted(roles),
+            "capabilities": capabilities,
+        }
+    )

endoreg_db/codemods/readme.md

@@ -0,0 +1,88 @@
+### install
+```
+uv add bowler fissix
+```
+
+### Dry-run (preview only)
+```
+python endoreg_db/codemods/rename_datetime_fields.py
+```
+
+### Run it (models only):
+```
+python endoreg_db/codemods/rename_datetime_fields.py --yes
+```
+
+### Verify what changed
+```
+git status
+git diff --name-only
+git diff
+```
+
+### Then check for any leftover legacy names in models (excluding migration history):
+```
+grep -RIn --exclude-dir='migrations' \
+  -E '\b(date_created|date_modified|last_update|date_updated|createdOn|updatedOn|modified_at|lastModified)\b' \
+  endoreg_db/models || true
+
+grep -RIn --exclude-dir='migrations' -E '\b(date_created|date_modified|last_update|date_updated|createdOn|updatedOn|modified_at|lastModified)\b' endoreg_db/models || true
+```
+
+### Fix F(..) expressions (if any)
+```
+# date_created -> created_at
+grep -Rl --exclude-dir='migrations' "F('date_created')" endoreg_db/models | xargs -r sed -i "s/F('date_created')/F('created_at')/g"
+grep -Rl --exclude-dir='migrations' 'F("date_created")' endoreg_db/models | xargs -r sed -i 's/F("date_created")/F("created_at")/g'
+
+# date_modified -> updated_at
+grep -Rl --exclude-dir='migrations' "F('date_modified')" endoreg_db/models | xargs -r sed -i "s/F('date_modified')/F('updated_at')/g"
+grep -Rl --exclude-dir='migrations' 'F("date_modified")' endoreg_db/models | xargs -r sed -i 's/F("date_modified")/F("updated_at")/g'
+```
+
+
+### Example: Fix f-strings / attribute refs (seen in raw_pdf.py, video.py)
+```
+# self.date_created -> self.created_at
+grep -Rl --exclude-dir='migrations' 'self\.date_created' endoreg_db/models | xargs -r sed -i 's/self\.date_created/self.created_at/g'
+# self.date_modified -> self.updated_at
+grep -Rl --exclude-dir='migrations' 'self\.date_modified' endoreg_db/models | xargs -r sed -i 's/self\.date_modified/self.updated_at/g'
+```
+
+### Fix string literals in .values(), .order_by(), dict keys
+```
+# double-quoted keys
+grep -Rl --exclude-dir='migrations' --include="*.py" '"date_created"' endoreg_db/models | xargs -r sed -i 's/"date_created"/"created_at"/g'
+grep -Rl --exclude-dir='migrations' --include="*.py" '"date_modified"' endoreg_db/models | xargs -r sed -i 's/"date_modified"/"updated_at"/g'
+grep -Rl --exclude-dir='migrations' --include="*.py" '"last_update"'  endoreg_db/models | xargs -r sed -i 's/"last_update"/"updated_at"/g'
+grep -Rl --exclude-dir='migrations' --include="*.py" '"date_updated"' endoreg_db/models | xargs -r sed -i 's/"date_updated"/"updated_at"/g'
+
+# single-quoted keys
+grep -Rl --exclude-dir='migrations' --include="*.py" "'date_created'" endoreg_db/models | xargs -r sed -i "s/'date_created'/'created_at'/g"
+grep -Rl --exclude-dir='migrations' --include="*.py" "'date_modified'" endoreg_db/models | xargs -r sed -i "s/'date_modified'/'updated_at'/g"
+grep -Rl --exclude-dir='migrations' --include="*.py" "'last_update'"  endoreg_db/models | xargs -r sed -i "s/'last_update'/'updated_at'/g"
+grep -Rl --exclude-dir='migrations' --include="*.py" "'date_updated'" endoreg_db/models | xargs -r sed -i "s/'date_updated'/'updated_at'/g"
+
+# order_by("-...") style
+grep -Rl --exclude-dir='migrations' --include="*.py" '"-date_created"' endoreg_db/models | xargs -r sed -i 's/"-date_created"/"-created_at"/g'
+grep -Rl --exclude-dir='migrations' --include="*.py" "'-date_created'" endoreg_db/models | xargs -r sed -i "s/'-date_created'/'-created_at'/g"
+grep -Rl --exclude-dir='migrations' --include="*.py" '"-date_modified"' endoreg_db/models | xargs -r sed -i 's/"-date_modified"/"-updated_at"/g'
+grep -Rl --exclude-dir='migrations' --include="*.py" "'-date_modified'" endoreg_db/models | xargs -r sed -i "s/'-date_modified'/'-updated_at'/g"
+```
+
+
+### Re-scan to confirm
+```
+grep -RIn --exclude-dir='migrations' \
+  -E '\b(date_created|date_modified|last_update|date_updated|createdOn|updatedOn|modified_at|lastModified)\b' \
+  endoreg_db/models || true
+```
+
+
+### Migrations
+```
+python manage.py makemigrations endoreg_db
+python manage.py migrate
+```
+
+

endoreg_db/codemods/rename_datetime_fields.py

@@ -0,0 +1,99 @@
+# endoreg_db/codemods/rename_datetime_fields.py
+from bowler import Query
+from pathlib import Path
+import argparse
+import yaml
+import sys
+
+# Paths
+BASE = Path(__file__).resolve().parents[1]  # .../endoreg_db
+RENAMES_YML = BASE / "renames.yml"
+DEFAULT_TARGETS = ["endoreg_db/models"]  # safer default
+EXCLUDE_DIR_NAMES = {"migrations", "__pycache__"}
+
+
+def load_renames():
+    if not RENAMES_YML.exists():
+        print(f"ERROR: renames.yml not found at {RENAMES_YML}", file=sys.stderr)
+        sys.exit(2)
+    data = yaml.safe_load(RENAMES_YML.read_text()) or {}
+    if not isinstance(data, dict) or not data:
+        print("ERROR: renames.yml is empty or not a mapping.", file=sys.stderr)
+        sys.exit(2)
+    return data
+
+
+def iter_python_targets(paths):
+    """Yield *.py files under given paths, excluding migrations and caches."""
+    for p in map(Path, paths):
+        if p.is_file() and p.suffix == ".py":
+            if not any(part in EXCLUDE_DIR_NAMES for part in p.parts):
+                yield str(p)
+        elif p.is_dir():
+            for f in p.rglob("*.py"):
+                if any(part in EXCLUDE_DIR_NAMES for part in f.parts):
+                    continue
+                yield str(f)
+
+
+def build_query(files):
+    # Bowler can take a list of files; we’ve already filtered them
+    return Query(list(files))
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        description="Rename legacy datetime fields to standardized names."
+    )
+    parser.add_argument(
+        "targets",
+        nargs="*",
+        help="Files/dirs to process. Default: endoreg_db/models",
+    )
+    parser.add_argument(
+        "--yes",
+        action="store_true",
+        help="Apply changes (write). Omit for a dry run.",
+    )
+    parser.add_argument(
+        "--silent",
+        action="store_true",
+        help="Reduce output verbosity.",
+    )
+    args = parser.parse_args(argv)
+
+    targets = args.targets or DEFAULT_TARGETS
+    if args.targets == []:
+        print(
+            "NOTICE: Using default target 'endoreg_db/models'. "
+            "Pass explicit paths to broaden scope.",
+            file=sys.stderr,
+        )
+
+    files = list(iter_python_targets(targets))
+    if not files:
+        print("No Python files found to process.", file=sys.stderr)
+        return 0
+
+    renames = load_renames()
+    q = build_query(files)
+
+    # Build transforms
+    for old, new in renames.items():
+        # obj.date_created  -> obj.created_at
+        q.select_attribute(old).rename(new)
+        # LHS or bare names: date_created = models.DateTimeField(...)
+        q.select_var(old).rename(new)
+
+    # Execute (dry-run by default)
+    q.execute(write=args.yes, silent=args.silent)
+    if not args.yes:
+        print(
+            "\nDry run complete. Re-run with --yes to apply changes.",
+            file=sys.stderr,
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

endoreg_db/config/env.py

@@ -0,0 +1,106 @@
+"""
+Centralized environment configuration for EndoReg-DB.
+
+This module is the single place to read environment variables and .env files.
+It avoids loading .env during pytest, and provides typed helpers.
+No Django imports here to prevent early settings configuration.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+# Detect pytest early to avoid loading .env in test runs
+IS_PYTEST = bool(os.environ.get("PYTEST_CURRENT_TEST"))
+
+# Compute repository BASE_DIR (repo root). This file is endoreg_db/config/env.py.
+BASE_DIR = Path(__file__).resolve().parents[2]
+
+# Optional: load .env only when not under pytest
+_DOTENV_LOADED = False
+try:
+    if not IS_PYTEST:
+        import dotenv
+
+        dotenv.load_dotenv()
+        _DOTENV_LOADED = True
+except Exception:
+    # dotenv is optional, ignore errors
+    _DOTENV_LOADED = False
+
+
+def _get(key: str, default: Optional[str] = None) -> Optional[str]:
+    return os.environ.get(key, default)
+
+
+def env_str(key: str, default: str = "") -> str:
+    val = _get(key)
+    return val if val is not None else default
+
+
+def env_bool(key: str, default: bool = False) -> bool:
+    val = _get(key)
+    if val is None:
+        return default
+    return str(val).strip().lower() in {"1", "true", "yes", "on"}
+
+
+def env_int(key: str, default: int = 0) -> int:
+    val = _get(key)
+    if val is None:
+        return default
+    try:
+        return int(str(val).strip())
+    except Exception:
+        return default
+
+
+def env_path(key: str, default_relative: str) -> Path:
+    """Return an absolute path. If env is relative, resolve under BASE_DIR."""
+    val = _get(key)
+    if not val:
+        p = BASE_DIR / default_relative
+    else:
+        p = Path(val)
+        if not p.is_absolute():
+            p = (BASE_DIR / p).resolve()
+    return p
+
+
+def snapshot() -> Dict[str, Any]:
+    """Return a snapshot of relevant config for debugging/logging."""
+    keys = [
+        # Core
+        "DJANGO_SETTINGS_MODULE",
+        "TIME_ZONE",
+        # Paths
+        "STORAGE_DIR",
+        "ASSET_DIR",
+        "STATIC_URL",
+        "MEDIA_URL",
+        # Dev DB
+        "DEV_DB_ENGINE",
+        "DEV_DB_NAME",
+        # Test DB
+        "TEST_DB_ENGINE",
+        "TEST_DB_NAME",
+        "TEST_DB_FILE",
+        # Flags
+        "RUN_VIDEO_TESTS",
+        "SKIP_EXPENSIVE_TESTS",
+    ]
+    data: Dict[str, Any] = {k: os.environ.get(k) for k in keys}
+    data.update(
+        {
+            "IS_PYTEST": IS_PYTEST,
+            "DOTENV_LOADED": _DOTENV_LOADED,
+            "BASE_DIR": str(BASE_DIR),
+        }
+    )
+    return data
+
+
+# Back-compat short aliases used by settings modules
+ENV = os.environ.get

endoreg_db/config/settings/__init__.py

@@ -0,0 +1,6 @@
+# Config settings package
+import os
+
+# If running under pytest, force test settings early to avoid .env leakage
+if os.environ.get('PYTEST_CURRENT_TEST'):
+    os.environ['DJANGO_SETTINGS_MODULE'] = 'endoreg_db.config.settings.test'