ccp4i2-api 0.3.0__py3-none-any.whl

ccp4i2_api/__init__.py

@@ -0,0 +1,13 @@
+"""Shared API contract for CCP4i2 and consumers.
+
+This package is the Python half of a bilingual API library; the TypeScript
+half is published as ``@ccp4/ccp4i2-api``. Both halves implement the same
+canonical bearer-token format, 401 response shape, and typed payloads
+carried over the authenticated channel.
+
+See the package README for current status and
+``docs/CCP4I2_SERVICE_CONTRACT.md`` in the ccp4i2 monorepo for the
+contract specification.
+"""
+
+__version__ = "0.3.0"

ccp4i2_api/drf.py

@@ -0,0 +1,58 @@
+"""DRF authentication classes for CCP4i2.
+
+These classes work in tandem with the middleware in
+``ccp4i2_api.middleware`` — the middleware validates the bearer token
+and sets ``request.user`` plus the ``REQUEST_FLAG_ATTR`` trust flag; the
+DRF auth class checks the flag and surfaces ``request.user`` to DRF's
+``IsAuthenticated`` permission.
+"""
+
+from rest_framework.authentication import BaseAuthentication
+
+from .middleware.base import REQUEST_FLAG_ATTR
+
+
+class AzureADAuthentication(BaseAuthentication):
+    """
+    DRF authentication class that uses the user set by AzureADAuthMiddleware.
+
+    This allows DRF's IsAuthenticated permission to work with our middleware.
+    The middleware does the actual JWT validation; this class just passes
+    the authenticated user to DRF.
+
+    In dev/Electron mode (CCP4I2_REQUIRE_AUTH not set), the middleware
+    auto-assigns a dev_admin user, which this class also recognizes.
+
+    Security: Only trusts users when our middleware has explicitly processed
+    the request (marked by ``REQUEST_FLAG_ATTR`` attribute). This prevents
+    spoofing attacks where a request might have ``request.user`` set by
+    some other means.
+
+    Note: this class is bound to the trust flag, not to the AzureAD chain
+    specifically; it works equally for any middleware that inherits from
+    ``BaseAuthMiddleware`` (e.g., LocalSessionAuthMiddleware in desktop
+    mode), because they all set the same flag.
+    """
+
+    def authenticate(self, request):
+        """
+        Return the user if already authenticated by middleware, None otherwise.
+
+        Returns:
+            Tuple of (user, None) if authenticated, None if not.
+        """
+        # Check if middleware already validated and set user
+        # The middleware sets these attributes on the underlying Django request
+        django_request = getattr(request, '_request', request)
+
+        # Security check: only trust users set by our middleware
+        # This prevents spoofing where request.user might be set elsewhere
+        if not getattr(django_request, REQUEST_FLAG_ATTR, False):
+            return None
+
+        # Middleware ran - trust the user it set
+        user = getattr(django_request, 'user', None)
+        if user and user.is_authenticated and not user.is_anonymous:
+            return (user, None)
+
+        return None

ccp4i2_api/exceptions.py

@@ -0,0 +1,18 @@
+"""Exceptions used by the shared auth middleware contract."""
+
+
+class AuthenticationFailed(Exception):
+    """Raised by ``BaseAuthMiddleware.authenticate()`` to signal a 401.
+
+    The exception's first argument is the message returned in the canonical
+    401 response body (``{"success": false, "error": "..."}``).
+    """
+
+
+class AuthorizationFailed(Exception):
+    """Raised by ``BaseAuthMiddleware.authenticate()`` to signal a 403.
+
+    Use when the request is *authenticated* (we know who is calling) but
+    *not authorized* (e.g., not a member of an allowed group). The first
+    argument is the message returned in the canonical 403 response body.
+    """

ccp4i2_api/middleware/__init__.py

@@ -0,0 +1,23 @@
+"""Django middleware shipped by the shared auth package.
+
+Each module in this package implements one auth scheme; consumers select
+which to enable via Django ``MIDDLEWARE`` settings. All non-dev schemes
+inherit from ``BaseAuthMiddleware`` (or will, after the AzureAD refactor),
+which defines the canonical 401 response shape and the ``REQUEST_FLAG_ATTR``
+trust signal.
+"""
+
+from .azure_ad import AzureADAuthMiddleware
+from .base import REQUEST_FLAG_ATTR, BaseAuthMiddleware
+from .dev import DevAuthMiddleware
+from .dev_admin import DevAdminMiddleware
+from .local_session import LocalSessionAuthMiddleware
+
+__all__ = [
+    "AzureADAuthMiddleware",
+    "BaseAuthMiddleware",
+    "DevAdminMiddleware",
+    "DevAuthMiddleware",
+    "LocalSessionAuthMiddleware",
+    "REQUEST_FLAG_ATTR",
+]

ccp4i2_api/middleware/azure_ad.py

@@ -0,0 +1,413 @@
+"""
+Azure AD JWT validation middleware for CCP4i2.
+
+This middleware validates Azure AD JWT tokens on incoming requests when
+CCP4I2_REQUIRE_AUTH=true is set. It supports both:
+
+1. Authorization header: "Bearer <token>"
+2. X-MS-TOKEN-AAD-ACCESS-TOKEN header (set by Azure Container Apps Easy Auth)
+
+Configuration environment variables:
+- CCP4I2_REQUIRE_AUTH: Set to "true" to enable authentication (default: false)
+- AZURE_AD_TENANT_ID: Your Azure AD tenant ID
+- AZURE_AD_CLIENT_ID: Your Azure AD app registration client ID
+
+The middleware validates:
+- Token signature (using Azure AD's public keys)
+- Token expiration
+- Audience (must match client ID)
+- Issuer (must match Azure AD tenant)
+"""
+
+import json
+import logging
+import os
+import ssl
+import time
+from typing import Optional, Tuple
+from urllib.error import URLError
+from urllib.request import urlopen
+
+import certifi
+from django.contrib.auth import get_user_model
+from django.http import HttpRequest, HttpResponse
+
+from ..exceptions import AuthenticationFailed, AuthorizationFailed
+from .base import BaseAuthMiddleware
+
+logger = logging.getLogger(__name__)
+
+
+class AzureADTokenValidator:
+    """Validates Azure AD JWT tokens."""
+
+    def __init__(self, tenant_id: str, client_id: str):
+        self.tenant_id = tenant_id
+        self.client_id = client_id
+        self.issuer = f"https://login.microsoftonline.com/{tenant_id}/v2.0"
+        self.jwks_uri = f"https://login.microsoftonline.com/{tenant_id}/discovery/v2.0/keys"
+        self._keys_cache: Optional[dict] = None
+        self._keys_cache_time: float = 0
+        self._keys_cache_ttl: float = 3600  # 1 hour
+
+    def _get_signing_keys(self) -> dict:
+        """Fetch Azure AD's public signing keys (JWKS)."""
+        now = time.time()
+
+        # Return cached keys if still valid
+        if self._keys_cache and (now - self._keys_cache_time) < self._keys_cache_ttl:
+            return self._keys_cache
+
+        try:
+            # Use certifi's certificate bundle for SSL verification
+            ssl_context = ssl.create_default_context(cafile=certifi.where())
+            with urlopen(self.jwks_uri, timeout=10, context=ssl_context) as response:
+                jwks = json.loads(response.read().decode("utf-8"))
+                self._keys_cache = {key["kid"]: key for key in jwks.get("keys", [])}
+                self._keys_cache_time = now
+                logger.debug(f"Fetched {len(self._keys_cache)} signing keys from Azure AD")
+                return self._keys_cache
+        except URLError as e:
+            logger.error(f"Failed to fetch Azure AD signing keys: {e}")
+            # Return stale cache if available, otherwise raise
+            if self._keys_cache:
+                logger.warning("Using stale signing keys cache")
+                return self._keys_cache
+            raise
+
+    def validate_token(self, token: str) -> Tuple[bool, Optional[dict], Optional[str]]:
+        """
+        Validate a JWT token.
+
+        Returns:
+            Tuple of (is_valid, claims_dict, error_message)
+        """
+        try:
+            import jwt
+            from jwt import PyJWK
+        except ImportError:
+            logger.error("PyJWT not installed. Run: pip install PyJWT[crypto]")
+            return False, None, "Server configuration error: PyJWT not installed"
+
+        try:
+            # Decode header to get key ID
+            unverified_header = jwt.get_unverified_header(token)
+            kid = unverified_header.get("kid")
+
+            if not kid:
+                return False, None, "Token missing key ID (kid)"
+
+            # Get the signing key
+            keys = self._get_signing_keys()
+            if kid not in keys:
+                # Key not found - try refreshing the cache
+                self._keys_cache = None
+                keys = self._get_signing_keys()
+                if kid not in keys:
+                    return False, None, f"Unknown signing key: {kid}"
+
+            key_data = keys[kid]
+
+            # Construct signing key directly from cached JWK data
+            # (avoids PyJWKClient making its own HTTPS request)
+            jwk = PyJWK.from_dict(key_data)
+            signing_key = jwk.key
+
+            # Decode and validate the token
+            claims = jwt.decode(
+                token,
+                signing_key,
+                algorithms=["RS256"],
+                audience=self.client_id,
+                issuer=self.issuer,
+                options={
+                    "verify_signature": True,
+                    "verify_exp": True,
+                    "verify_aud": True,
+                    "verify_iss": True,
+                },
+            )
+
+            logger.debug(f"Token validated for subject: {claims.get('sub', 'unknown')}")
+            return True, claims, None
+
+        except jwt.ExpiredSignatureError:
+            return False, None, "Token has expired"
+        except jwt.InvalidAudienceError:
+            return False, None, "Invalid token audience"
+        except jwt.InvalidIssuerError:
+            return False, None, "Invalid token issuer"
+        except jwt.InvalidSignatureError:
+            return False, None, "Invalid token signature"
+        except jwt.DecodeError as e:
+            return False, None, f"Token decode error: {e}"
+        except Exception as e:
+            logger.exception("Unexpected error validating token")
+            return False, None, f"Token validation error: {e}"
+
+
+# Singleton validator instance
+_validator: Optional[AzureADTokenValidator] = None
+
+
+def get_validator() -> Optional[AzureADTokenValidator]:
+    """Get or create the token validator instance."""
+    global _validator
+
+    if _validator is not None:
+        return _validator
+
+    tenant_id = os.environ.get("AZURE_AD_TENANT_ID")
+    client_id = os.environ.get("AZURE_AD_CLIENT_ID")
+
+    if not tenant_id or not client_id:
+        logger.warning(
+            "AZURE_AD_TENANT_ID and AZURE_AD_CLIENT_ID must be set for authentication. "
+            "Authentication is disabled."
+        )
+        return None
+
+    _validator = AzureADTokenValidator(tenant_id, client_id)
+    return _validator
+
+
+def is_auth_required() -> bool:
+    """Check if authentication is required."""
+    return os.environ.get("CCP4I2_REQUIRE_AUTH", "").lower() in ("true", "1", "yes")
+
+
+def extract_token(request: HttpRequest) -> Optional[str]:
+    """
+    Extract JWT token from request.
+
+    Checks in order:
+    1. Authorization header (Bearer token)
+    2. X-MS-TOKEN-AAD-ACCESS-TOKEN header (Azure Easy Auth)
+    3. Query parameter access_token (for file downloads/anchor links)
+    """
+    # Check Authorization header
+    auth_header = request.headers.get("Authorization", "")
+    if auth_header.startswith("Bearer "):
+        return auth_header[7:]
+
+    # Check Azure Easy Auth header
+    easy_auth_token = request.headers.get("X-MS-TOKEN-AAD-ACCESS-TOKEN")
+    if easy_auth_token:
+        return easy_auth_token
+
+    # Check query parameter (for file downloads - anchor links don't send headers)
+    query_token = request.GET.get("access_token")
+    if query_token:
+        return query_token
+
+    return None
+
+
+class AzureADAuthMiddleware(BaseAuthMiddleware):
+    """
+    Django middleware for Azure AD JWT validation. Cloud auth path.
+
+    Activates when ``CCP4I2_REQUIRE_AUTH=true`` (otherwise no-op, deferring
+    to whatever middleware comes next in the chain). When active, every
+    non-exempt request must carry a valid Azure AD JWT bearer token; the
+    middleware validates it, optionally enforces group-membership rules,
+    and gets-or-creates a Django user keyed on the cryptographic ``sub``.
+
+    The dev_admin auto-login path was deliberately split out into a
+    separate ``DevAdminMiddleware`` so a misconfigured cloud deploy
+    (REQUIRE_AUTH unset) cannot fall through to creating a superuser
+    automatically. See ``ccp4i2_api.middleware.dev_admin`` for the dev
+    path; the CCP4i2 settings module is responsible for picking exactly
+    one auth middleware based on the deployment shape.
+    """
+
+    # Paths that don't require authentication even when this middleware is active.
+    EXEMPT_PATHS = [
+        "/health",
+        "/healthz",
+        "/ready",
+        "/api/health",
+        "/api/ccp4i2/health",
+        "/api/ccp4i2/version",
+    ]
+
+    def __init__(self, get_response):
+        super().__init__(get_response)
+        if self.is_active():
+            logger.info("Azure AD authentication is ENABLED")
+            validator = get_validator()
+            if not validator:
+                logger.error(
+                    "Authentication required but AZURE_AD_TENANT_ID/AZURE_AD_CLIENT_ID not set!"
+                )
+        else:
+            logger.info("Azure AD authentication is DISABLED (CCP4I2_REQUIRE_AUTH not set)")
+
+    def is_active(self) -> bool:
+        return is_auth_required()
+
+    def __call__(self, request: HttpRequest) -> HttpResponse:
+        # Filter exempt paths *before* delegating to BaseAuthMiddleware so
+        # health checks and version probes always bypass authentication.
+        if self.is_active():
+            path = request.path.rstrip("/")
+            if any(path == exempt.rstrip("/") for exempt in self.EXEMPT_PATHS):
+                return self.get_response(request)
+        return super().__call__(request)
+
+    def authenticate(self, request: HttpRequest):
+        token = extract_token(request)
+        if not token:
+            raise AuthenticationFailed(
+                "Authentication required. Provide Authorization: Bearer <token>"
+            )
+
+        validator = get_validator()
+        if not validator:
+            # Server misconfiguration — AZURE_AD_TENANT_ID/CLIENT_ID missing.
+            # We surface this as a 401 because to the *caller* the result is
+            # the same as a token rejection: no auth happened, retry doesn't
+            # help. The error message and the operator-facing log line above
+            # tell the operator what to fix.
+            raise AuthenticationFailed("Server authentication not configured")
+
+        is_valid, claims, error = validator.validate_token(token)
+        if not is_valid:
+            raise AuthenticationFailed(error)
+
+        # Attach claims to request for downstream use.
+        request.azure_ad_claims = claims
+        azure_ad_sub = claims.get("sub")
+        request.azure_ad_user_id = azure_ad_sub
+
+        # Groups / Teams membership authorization.
+        self._enforce_group_membership(claims, azure_ad_sub)
+
+        email = self._extract_email(claims, request, azure_ad_sub)
+        request.azure_ad_email = email
+
+        return self._get_or_create_user(claims, azure_ad_sub, email)
+
+    # --- helper extractions kept private ------------------------------------
+
+    @staticmethod
+    def _enforce_group_membership(claims: dict, azure_ad_sub: str) -> None:
+        """Raise AuthorizationFailed if ALLOWED_AZURE_AD_GROUPS is set and
+        the user is not a member of any allowed group.
+
+        Requires:
+        1. Azure AD app configured to emit 'groups' claim (Token Configuration).
+        2. ALLOWED_AZURE_AD_GROUPS env var with comma-separated group IDs.
+        3. Azure AD Premium P1/P2 (for groups claim in tokens).
+        """
+        allowed_groups_str = os.environ.get("ALLOWED_AZURE_AD_GROUPS", "")
+        allowed_groups = [g.strip() for g in allowed_groups_str.split(",") if g.strip()]
+        if not allowed_groups:
+            logger.debug("Groups authorization not configured (ALLOWED_AZURE_AD_GROUPS not set)")
+            return
+
+        logger.debug(f"Groups authorization enabled. Allowed groups: {allowed_groups}")
+
+        # Group claims overage — user is in >200 groups, Azure AD substitutes
+        # _claim_names/_claim_sources for the full list. We can't validate
+        # locally; surface a friendly 403 so an admin can move the user to a
+        # dedicated app-access group with fewer members.
+        if "_claim_names" in claims or "_claim_sources" in claims:
+            logger.warning(
+                f"Group claims overage detected for user {azure_ad_sub[:8]}. "
+                "User is in >200 groups - cannot validate Teams membership from token. "
+                "Consider using a dedicated app access group with fewer members."
+            )
+            raise AuthorizationFailed(
+                "Your account has too many group memberships to verify "
+                "automatically. Please contact your administrator to be "
+                "added to a dedicated application access group."
+            )
+
+        user_groups = claims.get("groups", [])
+        logger.debug(f"User {azure_ad_sub[:8]}... has groups: {user_groups}")
+
+        if not any(group_id in allowed_groups for group_id in user_groups):
+            logger.warning(
+                f"Access denied for user {azure_ad_sub[:8]}... - not in authorized groups. "
+                f"User groups: {user_groups[:5]}{'...' if len(user_groups) > 5 else ''}, "
+                f"Required: {allowed_groups}"
+            )
+            raise AuthorizationFailed(
+                "You are not a member of an authorized group. This application "
+                "requires membership in the Newcastle Drug Discovery Unit team. "
+                "Please contact your administrator to request access."
+            )
+
+        logger.info(f"User {azure_ad_sub[:8]}... authorized via Teams/Groups membership")
+
+    @staticmethod
+    def _extract_email(claims: dict, request: HttpRequest, azure_ad_sub: str) -> str:
+        # Try multiple claim fields where email might be found.
+        email = (
+            claims.get("email")
+            or claims.get("preferred_username")
+            or claims.get("upn")  # User Principal Name
+            or claims.get("unique_name")  # Legacy claim
+        )
+
+        # Fallback: X-User-Email header (sent by frontend from MSAL account info).
+        # Secure because (1) JWT is already validated so we know WHO via 'sub';
+        # (2) 'sub' is the primary key, not email; (3) email is just for display.
+        if not email:
+            header_email = request.headers.get("X-User-Email")
+            if header_email:
+                logger.info(f"Using X-User-Email header for sub={azure_ad_sub[:8]}...")
+                email = header_email
+
+        if not email:
+            logger.warning(f"No email found for sub={azure_ad_sub}. Claims: {list(claims.keys())}")
+            email = f"user_{azure_ad_sub[:8]}@azuread.local"
+
+        return email
+
+    @staticmethod
+    def _get_or_create_user(claims: dict, azure_ad_sub: str, email: str):
+        # Extract name from claims (priority: given_name/family_name → 'name' → empty).
+        first_name = claims.get("given_name", "")
+        last_name = claims.get("family_name", "")
+        if not first_name and not last_name:
+            full_name = claims.get("name", "")
+            if full_name:
+                name_parts = full_name.strip().split()
+                if len(name_parts) >= 2:
+                    first_name = name_parts[0]
+                    last_name = " ".join(name_parts[1:])
+                elif len(name_parts) == 1:
+                    first_name = name_parts[0]
+
+        # Use 'sub' as the unique identifier (cryptographically verified) —
+        # prevents email-header spoofing from enabling impersonation.
+        User = get_user_model()
+        username = f"aad_{azure_ad_sub[:32]}"  # Stable username from sub
+        user, created = User.objects.get_or_create(
+            username=username,
+            defaults={
+                "email": email.lower(),
+                "first_name": first_name,
+                "last_name": last_name,
+            },
+        )
+        if created:
+            logger.info(f"Created user from Azure AD: {email} (sub={azure_ad_sub[:8]}...)")
+
+        # Update email and name if they changed or were initially missing.
+        updated = False
+        if user.email != email.lower():
+            user.email = email.lower()
+            updated = True
+        if first_name and user.first_name != first_name:
+            user.first_name = first_name
+            updated = True
+        if last_name and user.last_name != last_name:
+            user.last_name = last_name
+            updated = True
+        if updated:
+            user.save(update_fields=["email", "first_name", "last_name"])
+
+        return user

ccp4i2_api/middleware/base.py

@@ -0,0 +1,69 @@
+"""Common base class for CCP4i2 auth middleware.
+
+Subclasses implement ``is_active()`` (whether this middleware is configured
+to operate in the current process) and ``authenticate(request)`` (the
+auth-specific token-validation logic). The base class handles the rest of
+the request lifecycle: the canonical 401 response shape, setting
+``request.user``, and setting the trust flag that the matching DRF
+authentication class checks before honouring ``request.user`` (anti-
+spoofing, mirroring the existing AzureADAuthMiddleware contract).
+"""
+
+from django.http import HttpRequest, HttpResponse, JsonResponse
+
+from ..exceptions import AuthenticationFailed, AuthorizationFailed
+
+
+# Attribute name set on ``request`` after a successful authentication.
+# The DRF authentication class trusts ``request.user`` only when this is
+# set, preventing spoofing via direct attribute writes from other code.
+REQUEST_FLAG_ATTR = "_ccp4i2_api_middleware_ran"
+
+
+class BaseAuthMiddleware:
+    """Abstract base for CCP4i2 auth middleware.
+
+    Subclasses must implement:
+
+    * ``is_active(self) -> bool`` — return True iff this middleware should
+      attempt to authenticate. Typical implementation checks an env var
+      or Django setting.
+    * ``authenticate(self, request) -> User`` — return a Django User on
+      successful auth. Raise ``AuthenticationFailed`` to signal a 401.
+
+    When ``is_active()`` is False, the middleware is a no-op (the request
+    flows to the next middleware unchanged). This lets multiple subclasses
+    coexist in ``MIDDLEWARE`` without coupling between them; deployments
+    activate the right one via configuration (env var presence).
+    """
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request: HttpRequest) -> HttpResponse:
+        if not self.is_active():
+            return self.get_response(request)
+        try:
+            user = self.authenticate(request)
+        except AuthenticationFailed as exc:
+            return self._error_response(str(exc), status=401)
+        except AuthorizationFailed as exc:
+            return self._error_response(str(exc), status=403, prefix="Access denied")
+        request.user = user
+        setattr(request, REQUEST_FLAG_ATTR, True)
+        return self.get_response(request)
+
+    def is_active(self) -> bool:
+        raise NotImplementedError
+
+    def authenticate(self, request: HttpRequest):
+        raise NotImplementedError
+
+    @staticmethod
+    def _error_response(
+        message: str, status: int, prefix: str = "Authentication failed"
+    ) -> JsonResponse:
+        return JsonResponse(
+            {"success": False, "error": f"{prefix}: {message}"},
+            status=status,
+        )

ccp4i2_api/middleware/dev.py

@@ -0,0 +1,48 @@
+"""
+Development authentication middleware.
+
+Auto-authenticates requests in DEBUG mode for local development.
+This middleware should ONLY be used in development environments.
+"""
+
+from django.conf import settings
+from django.contrib.auth import get_user_model
+
+
+class DevAuthMiddleware:
+    """
+    Middleware that auto-authenticates requests in development mode.
+
+    If DEBUG=True and the user is not authenticated, this middleware
+    will automatically log them in as the dev user (configured via
+    DEV_USER_EMAIL setting).
+    """
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        # Only run in DEBUG mode and if user is not already authenticated
+        # Check hasattr because this may run before AuthenticationMiddleware
+        if settings.DEBUG:
+            user = getattr(request, 'user', None)
+            if user is None or not user.is_authenticated:
+                User = get_user_model()
+                dev_email = getattr(settings, 'DEV_USER_EMAIL', 'dev@localhost')
+
+                # Get or create the dev user
+                user, created = User.objects.get_or_create(
+                    email=dev_email,
+                    defaults={
+                        'username': dev_email.split('@')[0],
+                        'is_staff': True,
+                        'is_superuser': True,
+                    }
+                )
+
+                if created:
+                    print(f"Created dev user: {dev_email}")
+
+                request.user = user
+
+        return self.get_response(request)

ccp4i2_api/middleware/dev_admin.py

@@ -0,0 +1,65 @@
+"""Development-only auto-login middleware.
+
+Auto-assigns a ``dev_admin`` Django superuser to every request — useful
+for local Docker Compose development where you want CCP4i2 fully usable
+without any token machinery. **Never enable this in production.**
+
+Two defensive measures protect against accidental production exposure:
+
+1. ``is_active()`` returns False unless ``settings.DEBUG`` is True. Even
+   if this middleware is mistakenly listed in a production ``MIDDLEWARE``
+   setting, it refuses to activate.
+2. The CCP4i2 settings module only inserts this middleware as the
+   *fallback* branch (after LocalSession + AzureAD env-var checks) and
+   only when ``DEBUG`` is True. A production-shaped deploy with no auth
+   env vars set falls through to *no auth middleware at all*, leaving
+   requests as ``AnonymousUser`` — DRF's ``IsAuthenticated`` then 401s
+   them. This is strictly safer than the previous "auto-create dev_admin
+   on missing config" behaviour.
+
+This middleware deliberately does *not* mirror the previous AzureAD
+fallback's permissive default; it is opt-in via ``MIDDLEWARE`` and
+DEBUG-gated.
+"""
+
+import logging
+
+from django.conf import settings
+from django.contrib.auth import get_user_model
+from django.http import HttpRequest
+
+from .base import BaseAuthMiddleware
+
+logger = logging.getLogger(__name__)
+
+DEV_ADMIN_USERNAME = "dev_admin"
+DEV_ADMIN_EMAIL = "dev_admin@localhost"
+
+
+class DevAdminMiddleware(BaseAuthMiddleware):
+    """Auto-assigns a dev_admin superuser when DEBUG is True."""
+
+    def is_active(self) -> bool:
+        return getattr(settings, "DEBUG", False)
+
+    def authenticate(self, request: HttpRequest):
+        User = get_user_model()
+        user, created = User.objects.get_or_create(
+            username=DEV_ADMIN_USERNAME,
+            defaults={
+                "email": DEV_ADMIN_EMAIL,
+                "first_name": "Dev",
+                "last_name": "Admin",
+                "is_staff": True,
+                "is_superuser": True,
+            },
+        )
+        if created:
+            logger.info("Created dev_admin superuser for DEBUG mode")
+        # If a previous run created the user without admin flags, top them up
+        # so the dev experience stays consistent.
+        if not user.is_staff or not user.is_superuser:
+            user.is_staff = True
+            user.is_superuser = True
+            user.save(update_fields=["is_staff", "is_superuser"])
+        return user

ccp4i2_api/middleware/local_session.py

@@ -0,0 +1,65 @@
+"""Per-launch token middleware for the CCP4i2 desktop app.
+
+Validates ``Authorization: Bearer <token>`` against the secret in
+``CCP4I2_LOCAL_SESSION_TOKEN``, set by the Electron main process when
+spawning Django. If the env var is unset, the middleware is a no-op —
+cloud deployments use ``AzureADAuthMiddleware`` instead.
+
+Identity: the request is authenticated as the OS user who launched the
+desktop app. The OS-user-derived email is computed by Electron and passed
+via ``CCP4I2_LOCAL_USER_EMAIL`` (Electron sanitises the username so
+domain-joined Windows boxes don't produce malformed emails). If that env
+var is unset, the middleware falls back to a fixed default that is
+well-formed across all platforms.
+"""
+
+import hmac
+import os
+
+from django.contrib.auth import get_user_model
+from django.http import HttpRequest
+
+from ..exceptions import AuthenticationFailed
+from .base import BaseAuthMiddleware
+
+
+# RFC 6761 reserves ``.invalid`` for guaranteed-non-resolvable identifiers,
+# so this email is well-formed under Django's EmailValidator and cannot
+# collide with a real account on any platform.
+DEFAULT_DESKTOP_EMAIL = "desktop@ccp4i2.invalid"
+
+
+class LocalSessionAuthMiddleware(BaseAuthMiddleware):
+
+    def __init__(self, get_response):
+        super().__init__(get_response)
+        self.expected_token = os.environ.get("CCP4I2_LOCAL_SESSION_TOKEN")
+
+    def is_active(self) -> bool:
+        return self.expected_token is not None
+
+    def authenticate(self, request: HttpRequest):
+        auth = request.META.get("HTTP_AUTHORIZATION", "")
+        if not auth.startswith("Bearer "):
+            raise AuthenticationFailed("Missing Bearer token")
+        provided = auth[len("Bearer "):]
+        # Constant-time compare against length-extension / timing attacks.
+        # Loopback-only is unlikely to be exploitable, but the precedent
+        # is cheap to set for future cloud-side providers.
+        if not hmac.compare_digest(provided, self.expected_token):
+            raise AuthenticationFailed("Invalid local-session token")
+        return self._desktop_user()
+
+    @staticmethod
+    def _desktop_user():
+        User = get_user_model()
+        email = os.environ.get("CCP4I2_LOCAL_USER_EMAIL", DEFAULT_DESKTOP_EMAIL)
+        user, _ = User.objects.get_or_create(
+            email=email,
+            defaults={
+                "username": email.split("@")[0],
+                "is_staff": True,
+                "is_superuser": True,
+            },
+        )
+        return user

ccp4i2_api-0.3.0.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: ccp4i2-api
+Version: 0.3.0
+Summary: Shared API contract (auth, api-fetch, request/response types) for CCP4i2 and consumers
+Project-URL: Homepage, https://github.com/ccp4/ccp4i2/tree/django-sliced/packages/ccp4i2-api
+Project-URL: Repository, https://github.com/ccp4/ccp4i2
+Project-URL: Issues, https://github.com/ccp4/ccp4i2/issues
+Author: CCP4i2 contributors
+License: LGPL-3.0-or-later
+Requires-Python: >=3.9
+Requires-Dist: certifi>=2024.0.0
+Requires-Dist: django<5.0,>=4.2
+Requires-Dist: djangorestframework>=3.14
+Requires-Dist: pyjwt[crypto]>=2.10
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-django; extra == 'test'
+Description-Content-Type: text/markdown
+
+# `@ccp4/ccp4i2-api` / `ccp4i2-api`
+
+Shared API contract for CCP4i2 and consumers (CCP4i2 Compounds, third-party
+integrators) — auth handshake, api-fetch helpers, and request/response
+types. One package, two language artifacts: TypeScript on the client side
+(browser, Electron) and Python on the server side (Django middleware, DRF
+authentication). Both halves agree on the canonical bearer-token format,
+401 response shape, and the typed payloads carried over the authenticated
+channel.
+
+## Status
+
+**Draft v0 — published to npm + PyPI from the in-tree workspace.** Source
+of truth lives at
+[`packages/ccp4i2-api/`](https://github.com/ccp4/ccp4i2/tree/django-sliced/packages/ccp4i2-api)
+inside the `ccp4/ccp4i2` monorepo on the `django-sliced` branch and stays
+there. The companion `ccp4/ccp4i2-api` GitHub repo (created for the npm
+namespace and external visibility) does not host source.
+
+Versions `0.1.0`–`0.3.0` were published under the previous name
+`@ccp4/ccp4i2-auth` / `ccp4i2-auth`; the package was renamed at `0.3.0`
+because its scope had grown beyond auth to cover the broader API contract.
+The old name is unpublished/yanked; consumers should depend on
+`@ccp4/ccp4i2-api` and `ccp4i2-api` from `0.3.0` onward.
+
+Versioning follows semver from `0.x.y` onwards. The v0 contract is
+documented in
+[`docs/CCP4I2_SERVICE_CONTRACT.md`](https://github.com/ccp4/ccp4i2/blob/django-sliced/docs/CCP4I2_SERVICE_CONTRACT.md);
+field stability promises take effect from this version.
+
+## Layout
+
+| Path | Purpose |
+|---|---|
+| `src/` | TypeScript source. Built to `lib/` via `npm run build`. |
+| `lib/` | Built TypeScript output. Generated; gitignored. |
+| `dist/` | Python distribution output (`python -m build`). Generated; gitignored. Kept distinct from `lib/` so `twine upload dist/*` doesn't accidentally pick up TypeScript artefacts. |
+| `ccp4i2_api/` | Python source. Installed editable via `pip install -e .`. |
+| `tests/js/` | TypeScript tests (vitest, when added). |
+| `tests/python/` | Python tests (pytest, when added). |
+
+## Consumer wiring
+
+In-monorepo consumers can reference this package by local path for fast
+iteration; out-of-monorepo consumers pull the published versions.
+
+**TypeScript** — in-monorepo (`client/package.json`):
+
+```json
+"dependencies": {
+  "@ccp4/ccp4i2-api": "file:../packages/ccp4i2-api"
+}
+```
+
+(Path depth varies by consumer location.) Out-of-monorepo consumers use the
+published range, e.g. `"@ccp4/ccp4i2-api": "^0.3.0"`.
+
+**Python** — in-monorepo (`Docker/server/Dockerfile`, local dev setup):
+
+```bash
+pip install -e packages/ccp4i2-api/
+```
+
+Out-of-monorepo consumers `pip install ccp4i2-api>=0.3`.
+
+## Development
+
+```bash
+# TypeScript
+cd packages/ccp4i2-api
+npm install
+npm run build       # produces lib/
+npm run watch       # rebuilds on change
+
+# Python
+cd packages/ccp4i2-api
+ccp4-python -m pip install -e .
+ccp4-python -c "import ccp4i2_api; print(ccp4i2_api.__version__)"
+```

ccp4i2_api-0.3.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+ccp4i2_api/__init__.py,sha256=mVW2MQ8KF7wj8BwkSabwR13tZW7EBXIzMRB5cav-yTc,474
+ccp4i2_api/drf.py,sha256=xmhbkxIMKUdQkXUBiKz8iUycGbAF3c5S5wVKBhnN_sM,2329
+ccp4i2_api/exceptions.py,sha256=JnqIyRqDm2qOJAYIitaS1Wvhfvuetu8e5xAeL7MJsvc,664
+ccp4i2_api/middleware/__init__.py,sha256=xhRvvZ7FNF-gTyhAzLO6EWnvqMNsIJL9UxY3kqsvZhc,785
+ccp4i2_api/middleware/azure_ad.py,sha256=rIYl1A92CUAhpyCNAB8UoF2MIL3mI6Xl2R8VNOko4nI,16308
+ccp4i2_api/middleware/base.py,sha256=CwTXbZnzd-aywXyQnTgimmK5bD3nFMcIk45H7MWJL00,2726
+ccp4i2_api/middleware/dev.py,sha256=cOJuFNnPOnYQyJA4olDBlxD5tRPaH7xObI-5-8xAp-Q,1590
+ccp4i2_api/middleware/dev_admin.py,sha256=dP5qKgN5mSpQOtOaVMw7AVVHjsf3CU01SO2oxz22mmg,2444
+ccp4i2_api/middleware/local_session.py,sha256=ULTvKtMC3Db9bN3R0aOc6FbKn3Dfa6akLEV7XMg-lDQ,2497
+ccp4i2_api-0.3.0.dist-info/METADATA,sha256=vb95GqwsU2VIG95YbJeI_3EuNB1pY5ZmAJRJlLeIRNk,3660
+ccp4i2_api-0.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ccp4i2_api-0.3.0.dist-info/RECORD,,

ccp4i2_api-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any