endoreg-db 0.8.6.1__py3-none-any.whl → 0.8.8.9__py3-none-any.whl

endoreg_db/authz/auth.py

@@ -0,0 +1,74 @@
+import jwt
+import requests
+from jwt import PyJWKClient
+from django.conf import settings
+from django.contrib.auth import get_user_model
+from django.contrib.auth.models import Group
+from rest_framework import authentication, exceptions
+
+User = get_user_model()
+
+class KeycloakJWTAuthentication(authentication.BaseAuthentication):
+    """
+    Verifies Bearer JWTs against Keycloak JWKS.
+    Creates/updates a Django user and syncs groups if roles are present.
+    """
+
+    _jwks_client = None
+    _iss = None
+    _aud = None
+
+    @classmethod
+    def _init(cls):
+        if cls._jwks_client is None:
+            disc = requests.get(settings.OIDC_OP_DISCOVERY_ENDPOINT, timeout=5).json()
+            cls._jwks_client = PyJWKClient(disc["jwks_uri"])
+            cls._iss = disc["issuer"]
+        if cls._aud is None:
+            cls._aud = settings.OIDC_RP_CLIENT_ID
+
+    def authenticate(self, request):
+        auth = request.META.get("HTTP_AUTHORIZATION", "")
+        if not auth.startswith("Bearer "):
+            return None
+
+        token = auth.split(" ", 1)[1].strip()
+        try:
+            self._init()
+            signing_key = self._jwks_client.get_signing_key_from_jwt(token).key
+            claims = jwt.decode(
+                token,
+                signing_key,
+                algorithms=["RS256"],
+                audience=self._aud,
+                issuer=self._iss,
+                options={"require": ["exp", "iat", "iss"]},
+            )
+        except Exception as e:
+            raise exceptions.AuthenticationFailed(f"Invalid token: {e}")
+
+        username = claims.get("preferred_username") or claims.get("sub")
+        if not username:
+            raise exceptions.AuthenticationFailed("Token missing username/sub")
+
+        user, _ = User.objects.get_or_create(
+            username=username,
+            defaults={
+                "email": claims.get("email", ""),
+                "first_name": (claims.get("given_name") or "")[:150],
+                "last_name": (claims.get("family_name") or "")[:150],
+            },
+        )
+
+        # Optional: sync Django groups for API users too
+        roles = set(claims.get("roles", []) or [])
+        roles.update((claims.get("realm_access") or {}).get("roles", []) or [])
+        if roles:
+            groups = []
+            for r in roles:
+                grp, _ = Group.objects.get_or_create(name=r)
+                groups.append(grp)
+            user.groups.set(groups)
+            user.save()
+
+        return (user, None)

endoreg_db/authz/backends.py

@@ -0,0 +1,168 @@
+# endoreg_db/authz/backends.py
+#
+# Purpose:
+#   Authenticate browser users via OIDC (Keycloak), create/update a Django User on first login,
+#   and sync Keycloak *realm roles* into Django Groups so DRF permissions can check them.
+#
+# Flow:
+#   /oidc/authenticate/ → Keycloak login → /oidc/callback/ → this backend verifies ID token
+#   and returns a Django User instance. We then:
+#     - create the user on first login (create_user)
+#     - update profile fields on later logins (update_user)
+#     - sync roles → Django groups (so request.user.groups contains "data:read", etc.)
+#
+# Notes:
+#   - We assume you added a Keycloak mapper so roles appear either as a flat "roles" claim,
+#     or the standard "realm_access": {"roles": [...]}.
+#   - We *replace* the user's groups each login to match Keycloak (source of truth).
+#   - If you also need *client roles* (per-client), see the optional code in _extract_realm_roles().
+#
+# Settings that enable this backend (in config/settings/dev.py):
+#   AUTHENTICATION_BACKENDS = (
+#       "endoreg_db.authz.backends.KeycloakOIDCBackend",
+#       "django.contrib.auth.backends.ModelBackend",
+#   )
+
+from mozilla_django_oidc.auth import OIDCAuthenticationBackend
+from django.contrib.auth import get_user_model
+from django.contrib.auth.models import Group
+
+User = get_user_model()
+
+
+def _extract_realm_roles(claims):
+    """
+    Extract Keycloak *realm* roles from ID token claims.
+
+    We support two common forms:
+      1) A custom 'roles' flat claim (if you added a "roles-flat" mapper in Keycloak)
+         e.g.,  "roles": ["data:read", "data:write"]
+      2) The standard 'realm_access.roles' structure from Keycloak
+         e.g.,  "realm_access": {"roles": ["data:read", "data:write"]}
+
+    Returns:
+        set[str]: unique, non-empty role names.
+    """
+    roles = set()
+
+    # 1) Custom/flat roles claim (if you configured such a mapper in Keycloak)
+    roles.update(claims.get("roles", []) or [])
+
+    # 2) Standard Keycloak realm roles location
+    roles.update((claims.get("realm_access") or {}).get("roles", []) or [])
+
+    # OPTIONAL — include client roles as well (uncomment if you use them)
+    # resource_access = claims.get("resource_access") or {}
+    # for client_id, entry in resource_access.items():
+    #     for r in entry.get("roles", []) or []:
+    #         # Prefix client roles to avoid name collisions with realm roles
+    #         roles.add(f"{client_id}:{r}")
+
+    # Filter out any non-strings / empties, just in case
+    return {r for r in roles if isinstance(r, str) and r}
+
+
+class KeycloakOIDCBackend(OIDCAuthenticationBackend):
+    """
+    OIDC backend used by mozilla-django-oidc during login.
+
+    Responsibilities:
+      - Parse OIDC claims from Keycloak
+      - Create a new Django user on first login (create_user)
+      - Update the user on subsequent logins (update_user)
+      - Sync Keycloak roles → Django Groups so your PolicyPermission can check them
+    """
+
+    # Called by the base class when no existing user matches the claims.
+    def create_user(self, claims):
+        """
+        Create a new Django user on first OIDC login.
+
+        Args:
+            claims (dict): verified ID token claims (e.g., sub, email, names, roles...)
+
+        Returns:
+            User: the newly created Django user
+        """
+        # Preferred username is the most human-friendly identifier in Keycloak.
+        # Fallback to 'sub' (the stable subject identifier) if needed.
+        username = claims.get("preferred_username") or claims.get("sub")
+
+        # Create a minimal user; no password is set (OIDC will handle auth).
+        user = User.objects.create_user(
+            username=username,
+            email=claims.get("email", ""),
+            first_name=(claims.get("given_name") or "")[:150],
+            last_name=(claims.get("family_name") or "")[:150],
+        )
+
+        # Ensure Django groups mirror Keycloak roles immediately.
+        self._sync_groups(user, claims)
+        return user
+
+    # Called by the base class when a matching user already exists.
+    def update_user(self, user, claims):
+        """
+        Update existing Django user profile fields and resync groups.
+
+        Args:
+            user (User): existing Django user matched from claims
+            claims (dict): verified ID token claims
+
+        Returns:
+            User: the updated user
+        """
+        # Keep user profile in sync with IdP data (safe truncation to field max length)
+        user.email = claims.get("email", user.email)
+        user.first_name = (claims.get("given_name") or user.first_name)[:150]
+        user.last_name  = (claims.get("family_name") or user.last_name)[:150]
+        user.save(update_fields=["email", "first_name", "last_name"])
+
+        # Keep roles (groups) in sync on every login
+        self._sync_groups(user, claims)
+        return user
+
+    def _sync_groups(self, user, claims):
+        """
+        Make Django Groups *exactly* match the roles coming from Keycloak.
+
+        Behavior:
+          - For each incoming role, ensure a Django Group exists (get_or_create).
+          - Replace the user's groups with that exact set (source-of-truth = Keycloak).
+          - This means if a role is removed in Keycloak, it disappears in Django at next login.
+
+        If you prefer "additive only" behavior (never remove), change user.groups.set(...)
+        to a union/update pattern instead.
+        """
+        kc_roles = _extract_realm_roles(claims)
+
+        groups = []
+        for r in kc_roles:
+            grp, _ = Group.objects.get_or_create(name=r)
+            groups.append(grp)
+
+        # Replace membership to exactly match Keycloak roles
+        user.groups.set(groups)
+        user.save()
+
+        # OPTIONAL — map specific roles to Django staff/superuser:
+        # if "admin" in kc_roles or "realm-admin" in kc_roles:
+        #     user.is_staff = True
+        #     # user.is_superuser = True  # if you truly want full Django superuser
+        # else:
+        #     user.is_staff = False
+        # user.save(update_fields=["is_staff", "is_superuser"])
+
+    def filter_users_by_claims(self, claims):
+        """
+        Return the queryset of users matching the incoming claims.
+
+        The base class will use this to decide if create_user or update_user should run.
+
+        We match on preferred_username (case-insensitive). If not present, fall back to 'sub'.
+        """
+        username = claims.get("preferred_username") or claims.get("sub")
+        if not username:
+            # No usable identifier → no match
+            return self.UserModel.objects.none()
+        return self.UserModel.objects.filter(username__iexact=username)

endoreg_db/authz/management/commands/list_routes.py

@@ -0,0 +1,18 @@
+from django.core.management.base import BaseCommand
+from django.urls import get_resolver, URLPattern, URLResolver
+
+def iter_patterns(prefix, patterns):
+    for p in patterns:
+        if isinstance(p, URLPattern):
+            yield p
+        elif isinstance(p, URLResolver):
+            yield from iter_patterns(prefix, p.url_patterns)
+
+class Command(BaseCommand):
+    help = "List all URL names (useful to fill policy.py)"
+
+    def handle(self, *args, **options):
+        resolver = get_resolver()
+        for p in iter_patterns("", resolver.url_patterns):
+            if p.name:
+                self.stdout.write(p.name)

endoreg_db/authz/middleware.py

@@ -0,0 +1,83 @@
+# endoreg_db/authz/middleware.py
+#
+# Purpose:
+#   - For *browser requests* that hit protected API URLs (e.g., /api/...), make sure the user
+#     is authenticated via Keycloak. If not, redirect them to the OIDC login view and remember
+#     the original URL in ?next= so they come back to the same endpoint after login.
+#   - For *API clients* sending a Bearer token, DO NOT redirect (that would break API usage).
+#     Let DRF handle authentication/authorization and return 401/403 as appropriate.
+#
+# How it integrates:
+#   - This middleware is appended in settings via KEYCLOAK.EXTRA_MIDDLEWARE (in dev.py).
+#   - It assumes AuthenticationMiddleware has already run (declared in base.py), so
+#     request.user is available and accurate.
+#
+# Security model:
+#   - We only redirect *browser* requests (no Authorization header) that target protected prefixes.
+#   - We attach the original URL as ?next=<relative-path>. mozilla-django-oidc will read this
+#     and redirect back after a successful login.
+#   - Optional: you can sanitize/validate the next parameter to avoid open redirects,
+#     though using a relative path from request.get_full_path() is already safe.
+
+from django.shortcuts import redirect
+from django.conf import settings
+from urllib.parse import urlencode
+
+# Any URL path that starts with one of these prefixes is considered "protected" for browser UX.
+# You can add more prefixes if you want the same login-redirect behavior elsewhere
+# (e.g., PROTECTED_PREFIXES = ("/api/", "/reports/", "/dashboard/")).
+#PROTECTED_PREFIXES = ("/api/",)
+
+# Protect the SPA shell too (everything except static/assets/oidc)
+PROTECTED_PREFIXES = ("/",)  # catch-all; we'll skip known public paths below
+
+PUBLIC_PREFIXES = (
+    "/static/",
+    "/assets/",
+    "/media/",
+    "/favicon.ico",
+    "/oidc/",          # OIDC endpoints must stay public
+    "/__vite",         # if Vite dev assets ever used
+)
+
+class LoginRequiredForAPIsMiddleware:
+    """
+    For browser traffic:
+      - If a user hits a protected URL without being authenticated, redirect to OIDC login
+        and include ?next=<original-url> so the user returns to the same endpoint post-login.
+    For API clients:
+      - If the request has an "Authorization: Bearer <token>" header, do not redirect;
+        let DRF auth handle it (token flows expect 401/403, not 302).
+
+    """
+
+    def __init__(self, get_response): self.get_response = get_response
+
+    def __call__(self, request):
+        # request.path is the URL path without scheme/host/query (e.g., "/api/patients/").
+        # If for any reason it's None/empty, coerce to empty string so startswith won’t explode.
+        path = request.path or ""
+        # --- Exclusions so we don't block assets, HMR, OIDC endpoints, favicon, etc.
+        # Allow static, assets, vite HMR, favicon, and OIDC endpoints without redirect
+        # Skip public stuff
+        if path.startswith(PUBLIC_PREFIXES):
+            return self.get_response(request)
+
+        # If not protected, pass through (shouldn’t happen with PROTECTED_PREFIXES=('/' ,))
+        if not path.startswith(PROTECTED_PREFIXES):
+            return self.get_response(request)
+
+        # API/token clients never get redirected
+        auth = request.META.get("HTTP_AUTHORIZATION", "")
+        if auth.startswith("Bearer "):
+            return self.get_response(request)
+
+        # 3) Browser without session → redirect to OIDC
+        if not request.user.is_authenticated:
+            from django.conf import settings
+            from urllib.parse import urlencode
+            params = urlencode({"next": request.get_full_path()})
+            return redirect(f"{settings.LOGIN_URL}?{params}")
+
+        # 4) Authenticated → pass through
+        return self.get_response(request)

endoreg_db/authz/permissions.py

@@ -0,0 +1,127 @@
+# endoreg_db/authz/permissions.py
+#
+# Purpose
+# -------
+# Enforce your route → role policy:
+#   - In DEBUG: allow everything (dev convenience).
+#   - In PROD: look at the user's Django Groups (synced from Keycloak roles)
+#     and decide per-route using REQUIRED_ROLES and DEFAULT_ROLE_BY_METHOD.
+#
+# How it plugs in
+# ---------------
+# Add this class to DRF's global permission chain in settings (you already did):
+#   REST_FRAMEWORK["DEFAULT_PERMISSION_CLASSES"] = (
+#       "endoreg_db.utils.permissions.EnvironmentAwarePermission",
+#       "endoreg_db.authz.permissions.PolicyPermission",
+#   )
+# The first class gates "auth required in prod"; this class enforces *which role*
+# is needed, per route, using policy.py.
+#
+# Key ideas
+# ---------
+# - DRF route names for ViewSets are "<basename>-<action>", e.g., "patient-list".
+# - REQUIRED_ROLES maps these names to a role (e.g., "data:read"/"data:write").
+# - If a route isn’t listed, DEFAULT_ROLE_BY_METHOD is used ("GET"→read, writes→write).
+# - Role satisfaction rule (in policy.satisfies): "write ⇒ read".
+# - User roles come from Django Groups, set at OIDC login by your OIDC backend.
+
+from rest_framework.permissions import BasePermission
+from django.contrib.auth.models import AnonymousUser
+from django.utils.functional import cached_property
+from endoreg_db.utils.permissions import is_debug_mode
+from .policy import REQUIRED_ROLES, DEFAULT_ROLE_BY_METHOD, satisfies, get_needed_role
+import logging
+
+logger = logging.getLogger(__name__)
+
+def _normalized_route_name(request, view) -> str:
+    """
+    Return a stable, de-namespaced route name, e.g. 'patient-list'.
+    Prefer resolver_match.view_name (may be 'endoreg_db:patient-list'),
+    fallback to url_name, then class name.
+    """
+    rm = getattr(request, "resolver_match", None)
+    if rm:
+        # Try namespaced form first (strip namespace)
+        view_name = getattr(rm, "view_name", "") or ""
+        if view_name:
+            return view_name.split(":")[-1]
+        url_name = getattr(rm, "url_name", "") or ""
+        if url_name:
+            return url_name
+    return view.__class__.__name__
+
+def _route_name(request, view):
+    """
+    Resolve a stable name for the current endpoint.
+
+    For DRF ViewSets registered via DefaultRouter:
+      - request.resolver_match.url_name is typically "<basename>-<action>"
+        e.g., "patient-list", "patient-detail", "check_pe_exist"
+    For plain APIViews or function views with path(name="..."):
+      - .url_name is that explicit name.
+    Fallback:
+      - If resolver info is missing (edge cases), use the class name as a last resort.
+
+    NOTE: Namespaces (e.g., "api:patient-list") do not affect .url_name; it's just "patient-list".
+    """
+    rm = getattr(request, "resolver_match", None)
+    if rm and rm.url_name:
+        return rm.url_name
+    return view.__class__.__name__  # last-resort fallback (rarely used in practice)
+
+
+class PolicyPermission(BasePermission):
+    """
+    Enforce route→role mapping from policy.py.
+
+    Behavior:
+      - DEBUG: allow everything (keeps dev flow smooth).
+      - PROD: require authentication AND the right role.
+              Roles are read from request.user.groups (synced from Keycloak realm roles).
+
+    Why cached_property?
+      - REQUIRED_ROLES is a module-level dict; caching avoids re-reading it for every request.
+        (It remains live—if you edit the dict at runtime in tests, restart to refresh.)
+    """
+
+    @cached_property
+    def _required_roles(self):
+        return REQUIRED_ROLES
+
+    def has_permission(self, request, view):
+        route = _normalized_route_name(request, view)
+        method = (request.method or "").upper()
+
+        # 1) DEBUG bypass
+        if is_debug_mode():
+            logger.info("RBAC BYPASS (DEBUG): route=%s method=%s user=%s",
+                        route, method, getattr(getattr(request, "user", None), "username", "anon"))
+            return True
+
+        # 2) Must be authenticated
+        user = getattr(request, "user", None)
+        if not user or isinstance(user, AnonymousUser) or not user.is_authenticated:
+            logger.info("RBAC DENY (UNAUTH): route=%s method=%s", route, method)
+            return False
+
+        # 3) Determine needed role
+        needed = get_needed_role(route, method)
+        if not needed:
+          logger.info(
+            "RBAC DENY (NO ROLE): route=%s method=%s reason=no mapping",
+            route, method
+          )
+          return False
+
+        # 4) Collect roles and decide
+        user_roles = set(user.groups.values_list("name", flat=True))
+        allowed = satisfies(user_roles, needed)
+
+        logger.info(
+            "RBAC DECISION: route=%s method=%s need=%s user=%s roles=%s => %s",
+            route, method, needed, getattr(user, "username", "anon"),
+            sorted(user_roles), "ALLOW" if allowed else "DENY"
+        )
+
+        return allowed

endoreg_db/authz/policy.py

@@ -0,0 +1,218 @@
+"""
+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",
+
+    "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)