cc-auth 0.1.0__py3-none-any.whl

cc_auth/__init__.py

@@ -0,0 +1,30 @@
+"""
+cc-auth — Cloudflare Access JWT validation + RBAC for Python backends.
+
+Quickstart::
+
+    from cc_auth import CloudflareAuth, User
+
+    # No configuration required to get started.
+    # Set CF_ACCESS_GROUP_MAPPING for role-based access control.
+    auth = CloudflareAuth.from_env()
+
+    # FastAPI
+    app.add_middleware(auth.middleware(exclude_paths=["/health"]))
+
+    @router.get("/me")
+    async def me(user: User = Depends(auth.current_user)):
+        return {"email": user.email, "roles": user.roles}
+
+    @router.delete("/item/{id}")
+    async def delete(id: str, user: User = Depends(auth.require_role("admin"))):
+        ...
+"""
+
+from .core import CloudflareAuth
+from .exceptions import AuthError
+from .exceptions import PermissionError as CCPermissionError
+from .identity import User
+
+__all__ = ["CloudflareAuth", "User", "AuthError", "CCPermissionError"]
+__version__ = "0.1.0"

cc_auth/core.py

@@ -0,0 +1,278 @@
+"""
+CloudflareAuth — the main entry point for the library.
+
+Instantiate once at application startup and pass it to your framework
+integration (middleware or dependency).
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Dict, List, Optional
+
+from .exceptions import AuthError
+from .identity import User
+from .validator import TokenValidator
+
+# Header and cookie names Cloudflare uses to carry the JWT.
+_CF_HEADER = "cf-access-jwt-assertion"       # lowercase after ASGI normalisation
+_CF_HEADER_RAW = "CF-Access-Jwt-Assertion"   # as sent by browsers / curl
+_CF_COOKIE = "CF_Authorization"
+
+
+class CloudflareAuth:
+    """
+    Validates Cloudflare Access JWTs and maps group memberships to roles.
+
+    Typical usage::
+
+        auth = CloudflareAuth.from_env()   # reads CF_ACCESS_GROUP_MAPPING
+
+        app.add_middleware(auth.middleware(exclude_paths=["/health"]))
+
+        @router.get("/me")
+        async def me(user: User = Depends(auth.current_user)):
+            return {"email": user.email, "roles": user.roles}
+
+        @router.delete("/item/{id}")
+        async def delete(id: str, user: User = Depends(auth.require_role("admin"))):
+            ...
+
+    The same instance should be reused for the lifetime of the application
+    so the JWKS key cache is shared across requests.
+    """
+
+    def __init__(
+        self,
+        team_domain: str,
+        role_groups: Optional[Dict[str, str]] = None,
+        _jwks_client=None,
+    ) -> None:
+        """
+        Args:
+            team_domain:  Your Cloudflare Zero Trust team domain,
+                          e.g. ``your-org.cloudflareaccess.com``.
+                          Use :meth:`from_env` to read this from the
+                          ``CF_TEAM_DOMAIN`` environment variable instead.
+            role_groups:  Optional mapping of Entra ID group Object ID → role name.
+                          Users whose group memberships match a key receive the
+                          corresponding role in ``User.roles``.  Users in groups not
+                          listed here are still authenticated; they just have no roles.
+            _jwks_client: For testing only — inject a pre-built ``PyJWKClient``
+                          (or any object with a ``get_signing_key_from_jwt`` method)
+                          to bypass the live JWKS fetch.
+        """
+        if not team_domain:
+            raise ValueError(
+                "team_domain is required. Pass your Cloudflare Zero Trust team domain "
+                "(e.g. 'your-org.cloudflareaccess.com') or set the CF_TEAM_DOMAIN "
+                "environment variable and use CloudflareAuth.from_env()."
+            )
+        self._validator = TokenValidator(team_domain, jwks_client=_jwks_client)
+        self._role_groups: Dict[str, str] = role_groups or {}
+
+    # ------------------------------------------------------------------
+    # Factory
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        group_mapping_env: str = "CF_ACCESS_GROUP_MAPPING",
+        required_groups_env: str = "CF_ACCESS_REQUIRED_GROUPS",
+        team_domain_env: str = "CF_TEAM_DOMAIN",
+        _jwks_client=None,
+    ) -> "CloudflareAuth":
+        """
+        Create a :class:`CloudflareAuth` instance from environment variables.
+
+        This is the recommended construction path for production services.
+        It keeps Entra ID group Object IDs out of source code and lets each
+        deployment choose its own allowed groups and roles.
+
+        Environment variables read:
+
+        ``CF_ACCESS_GROUP_MAPPING`` *(optional)*
+            JSON object mapping **role name → group Object ID**.
+            Role names are chosen by the application; they can be anything.
+            Note the order: role name comes first (human-readable), group ID
+            comes second (opaque).  The library inverts this internally.
+
+            Example::
+
+                CF_ACCESS_GROUP_MAPPING={"admins":"4fb32c31-...","developers":"6543851f-..."}
+
+        ``CF_ACCESS_REQUIRED_GROUPS`` *(optional)*
+            Comma-separated list of group Object IDs that are allowed to
+            access this application.  Each group is mapped to the role
+            ``"member"``.  Use this when you need allow/deny without
+            distinct named roles, e.g.::
+
+                CF_ACCESS_REQUIRED_GROUPS=4fb32c31-...,6543851f-...
+
+            Then enforce access with::
+
+                Depends(auth.require_role("member"))
+
+        ``CF_TEAM_DOMAIN`` *(required)*
+            Your Cloudflare Zero Trust team domain,
+            e.g. ``your-org.cloudflareaccess.com``.
+
+        Both ``CF_ACCESS_GROUP_MAPPING`` and ``CF_ACCESS_REQUIRED_GROUPS``
+        may be set simultaneously; their entries are merged.  If the same
+        group Object ID appears in both, ``CF_ACCESS_GROUP_MAPPING`` wins
+        (its role name takes precedence over ``"member"``).
+
+        Raises:
+            ValueError: If ``CF_ACCESS_GROUP_MAPPING`` is not valid JSON.
+        """
+        team_domain_override = os.getenv(team_domain_env, "").strip()
+
+        role_groups: Dict[str, str] = {}
+
+        required_raw = os.getenv(required_groups_env, "").strip()
+        if required_raw:
+            for gid in (g.strip() for g in required_raw.split(",") if g.strip()):
+                role_groups[gid] = "member"
+
+        mapping_raw = os.getenv(group_mapping_env, "").strip()
+        if mapping_raw:
+            try:
+                mapping: Dict[str, str] = json.loads(mapping_raw)
+            except json.JSONDecodeError as exc:
+                raise ValueError(
+                    f"{group_mapping_env} is not valid JSON: {exc}"
+                ) from exc
+            if not isinstance(mapping, dict):
+                raise ValueError(
+                    f"{group_mapping_env} must be a JSON object, got {type(mapping).__name__}"
+                )
+            # Env var format is {role_name: group_id}; internal format is {group_id: role_name}.
+            for role_name, group_id in mapping.items():
+                role_groups[str(group_id)] = str(role_name)
+
+        if not team_domain_override:
+            raise ValueError(
+                "CF_TEAM_DOMAIN environment variable is not set. "
+                "Set it to your Cloudflare Zero Trust team domain, "
+                "e.g. 'your-org.cloudflareaccess.com'."
+            )
+
+        return cls(
+            team_domain=team_domain_override,
+            role_groups=role_groups or None,
+            _jwks_client=_jwks_client,
+        )
+
+    # ------------------------------------------------------------------
+    # Core public API
+    # ------------------------------------------------------------------
+
+    def authenticate(self, token: str) -> User:
+        """
+        Validate ``token`` and return a :class:`User`.
+
+        Raises:
+            AuthError: If the token is invalid for any reason.
+        """
+        payload = self._validator.decode(token)
+
+        groups: List[str] = payload.get("groups") or []
+        roles: List[str] = list({
+            self._role_groups[g]
+            for g in groups
+            if g in self._role_groups
+        })
+
+        return User(
+            sub=payload.get("sub", ""),
+            email=payload.get("email", ""),
+            name=payload.get("name") or payload.get("email", ""),
+            groups=groups,
+            roles=roles,
+            raw=payload,
+        )
+
+    def extract_token(
+        self,
+        headers: Dict[str, str],
+        cookies: Optional[Dict[str, str]] = None,
+    ) -> Optional[str]:
+        """
+        Pull the JWT from ``CF-Access-Jwt-Assertion`` header (preferred, used by
+        API clients and Cloudflare service-to-service calls) or the
+        ``CF_Authorization`` cookie (set by Cloudflare for browser sessions).
+
+        Returns ``None`` if neither is present.
+        """
+        # ASGI headers are lowercase bytes; accept both forms.
+        token = (
+            headers.get(_CF_HEADER)
+            or headers.get(_CF_HEADER_RAW)
+        )
+        if not token and cookies:
+            token = cookies.get(_CF_COOKIE)
+        return token or None
+
+    # ------------------------------------------------------------------
+    # Framework integrations (imported lazily to avoid hard deps)
+    # ------------------------------------------------------------------
+
+    def middleware(self, exclude_paths=None):
+        """
+        Return an ASGI middleware class that validates every request.
+
+        Every route is protected automatically — no ``Depends(...)`` needed
+        on individual endpoints. Routes in ``exclude_paths`` bypass auth
+        entirely (useful for ``/health``, ``/metrics``, webhooks, etc.).
+
+        Usage::
+
+            # Protect everything
+            app.add_middleware(auth.middleware())
+
+            # Protect everything except /health and /metrics
+            app.add_middleware(auth.middleware(exclude_paths=["/health", "/metrics"]))
+
+        Routes that need the ``User`` object or role checks still use
+        ``Depends(auth.current_user)`` / ``Depends(auth.require_role(...))``,
+        but those are for accessing identity inside the handler — not for
+        protection, which the middleware already provides.
+        """
+        from .middleware import build_middleware
+        return build_middleware(self, exclude_paths=exclude_paths)
+
+    @property
+    def current_user(self):
+        """
+        FastAPI dependency that returns the authenticated :class:`User`.
+
+        Usage::
+
+            @router.get("/me")
+            async def me(user: User = Depends(auth.current_user)):
+                return {"email": user.email}
+        """
+        from .fastapi import build_current_user_dep
+        return build_current_user_dep(self)
+
+    def require_role(self, role: str):
+        """
+        FastAPI dependency that requires the user to hold ``role``.
+
+        Usage::
+
+            @router.delete("/item/{id}")
+            async def delete(id: str, user: User = Depends(auth.require_role("admin"))):
+                ...
+        """
+        from .fastapi import build_require_role_dep
+        return build_require_role_dep(self, role)
+
+    def require_any_role(self, roles: List[str]):
+        """
+        FastAPI dependency that requires the user to hold at least one of ``roles``.
+        """
+        from .fastapi import build_require_any_role_dep
+        return build_require_any_role_dep(self, roles)

cc_auth/exceptions.py

@@ -0,0 +1,22 @@
+"""
+Exceptions raised by cc-auth.
+
+These are thin wrappers so callers can catch auth errors specifically
+without importing from jwt or any other third-party library.
+"""
+
+
+class AuthError(Exception):
+    """Raised when a token cannot be verified (missing, expired, bad signature, wrong audience…)."""
+
+    def __init__(self, message: str, status_code: int = 401):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class PermissionError(Exception):
+    """Raised when the authenticated user does not hold the required role."""
+
+    def __init__(self, message: str = "Insufficient permissions", status_code: int = 403):
+        super().__init__(message)
+        self.status_code = status_code

cc_auth/fastapi.py

@@ -0,0 +1,92 @@
+"""
+FastAPI dependency factories.
+
+These are returned by CloudflareAuth.current_user, .require_role(), and
+.require_any_role() so callers never import from this module directly.
+
+This module is only loaded when the FastAPI integration is actually used
+(core.py imports it lazily), so top-level FastAPI/Starlette imports here
+are safe — they won't affect users who don't have FastAPI installed.
+
+Two usage patterns are supported:
+
+1. Middleware-first (recommended for most apps):
+   Add auth.middleware to the app; use auth.current_user / auth.require_role
+   in route dependencies.  The middleware has already validated the token and
+   stored the User on request.state.user — the dependency just reads it.
+
+2. Dependency-only (useful for testing or selective protection):
+   Skip the middleware; use auth.require_role as a route dependency.
+   The dependency extracts and validates the token itself.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List
+
+# Top-level imports so that FastAPI's get_type_hints() can resolve annotations
+# on dependency functions defined in this module.  This file is only imported
+# when the user is actually using the FastAPI integration (core.py lazy-loads it).
+from fastapi import Depends, Request
+from fastapi.exceptions import HTTPException
+
+from .exceptions import AuthError
+from .identity import User
+
+if TYPE_CHECKING:
+    from .core import CloudflareAuth
+
+
+def build_current_user_dep(auth: "CloudflareAuth"):
+    """Return a FastAPI dependency that resolves the current :class:`User`."""
+
+    async def current_user(request: Request):
+        # If middleware already resolved the user, reuse it.
+        user = getattr(request.state, "user", None)
+        if user is not None:
+            return user
+
+        # Dependency-only mode: extract and validate here.
+        headers = dict(request.headers)
+        cookies = dict(request.cookies)
+        token = auth.extract_token(headers, cookies)
+        if not token:
+            raise HTTPException(status_code=401, detail="Missing Cloudflare Access token")
+        try:
+            return auth.authenticate(token)
+        except AuthError as exc:
+            raise HTTPException(status_code=exc.status_code, detail=str(exc)) from exc
+
+    return current_user
+
+
+def build_require_role_dep(auth: "CloudflareAuth", role: str):
+    """Return a FastAPI dependency that requires the user to hold `role`."""
+
+    current_user = build_current_user_dep(auth)
+
+    async def require_role(user: User = Depends(current_user)):
+        if not user.has_role(role):
+            raise HTTPException(
+                status_code=403,
+                detail=f"Role '{role}' required",
+            )
+        return user
+
+    return require_role
+
+
+def build_require_any_role_dep(auth: "CloudflareAuth", roles: List[str]):
+    """Return a FastAPI dependency that requires the user to hold at least one of `roles`."""
+
+    current_user = build_current_user_dep(auth)
+
+    async def require_any_role(user: User = Depends(current_user)):
+        if not user.has_any_role(roles):
+            roles_str = ", ".join(f"'{r}'" for r in roles)
+            raise HTTPException(
+                status_code=403,
+                detail=f"One of these roles required: {roles_str}",
+            )
+        return user
+
+    return require_any_role

cc_auth/identity.py

@@ -0,0 +1,44 @@
+"""
+User identity resolved from a validated Cloudflare Access JWT.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+
+@dataclass
+class User:
+    """
+    Represents an authenticated user extracted from a Cloudflare Access JWT.
+
+    Attributes:
+        sub:    Unique user identifier (Cloudflare subject claim).
+        email:  User's email address.
+        name:   Display name (falls back to email if not present in token).
+        groups: List of Microsoft Entra ID group Object IDs the user belongs to.
+                Only populated when "Support groups" is enabled on the Azure AD
+                identity provider in Cloudflare Zero Trust.
+        roles:  Application-level role names mapped from groups by CloudflareAuth.
+                Empty if no role_groups mapping was provided.
+        raw:    Full decoded JWT payload — use for any claims not surfaced above.
+    """
+
+    sub: str
+    email: str
+    name: str
+    groups: List[str] = field(default_factory=list)
+    roles: List[str] = field(default_factory=list)
+    raw: Dict = field(default_factory=dict)
+
+    def has_role(self, role: str) -> bool:
+        """Return True if the user holds `role`."""
+        return role in self.roles
+
+    def has_any_role(self, roles: List[str]) -> bool:
+        """Return True if the user holds at least one of the given roles."""
+        return bool(set(roles) & set(self.roles))
+
+    def has_all_roles(self, roles: List[str]) -> bool:
+        """Return True if the user holds every one of the given roles."""
+        return set(roles).issubset(set(self.roles))

cc_auth/middleware.py

@@ -0,0 +1,70 @@
+"""
+ASGI middleware for Starlette / FastAPI.
+
+Validates the Cloudflare Access JWT on every incoming request and stores
+the resolved User on ``request.state.user``.  Routes that don't need
+authentication can ignore request.state.user entirely.
+
+Requests that carry an invalid token receive a 401 JSON response.
+Requests with no token at all also receive a 401 — if you need to allow
+unauthenticated requests for specific paths (e.g. health checks), exclude
+those paths with the ``exclude_paths`` option.
+"""
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Iterable, Optional
+
+if TYPE_CHECKING:
+    from .core import CloudflareAuth
+
+
+def build_middleware(auth: "CloudflareAuth", exclude_paths: Optional[Iterable[str]] = None):
+    """
+    Return an ASGI middleware class bound to `auth`.
+
+    Args:
+        auth:          The :class:`~cc_auth.CloudflareAuth` instance.
+        exclude_paths: Optional iterable of path prefixes that bypass auth
+                       (e.g. ``["/health", "/metrics"]``).
+    """
+    from starlette.middleware.base import BaseHTTPMiddleware
+    from starlette.requests import Request
+    from starlette.responses import JSONResponse
+
+    from .exceptions import AuthError
+
+    _excluded = list(exclude_paths or [])
+
+    class CloudflareAccessMiddleware(BaseHTTPMiddleware):
+        async def dispatch(self, request: Request, call_next):
+            # Skip auth for excluded paths.
+            for prefix in _excluded:
+                if request.url.path.startswith(prefix):
+                    return await call_next(request)
+
+            # Build header dict (ASGI headers are bytes).
+            headers = {
+                k.decode(): v.decode()
+                for k, v in request.headers.raw
+            }
+            cookies = dict(request.cookies)
+
+            token = auth.extract_token(headers, cookies)
+            if not token:
+                return JSONResponse(
+                    {"detail": "Missing Cloudflare Access token"},
+                    status_code=401,
+                )
+
+            try:
+                request.state.user = auth.authenticate(token)
+            except AuthError as exc:
+                return JSONResponse(
+                    {"detail": str(exc)},
+                    status_code=exc.status_code,
+                )
+
+            return await call_next(request)
+
+    return CloudflareAccessMiddleware

cc_auth/validator.py

@@ -0,0 +1,85 @@
+"""
+JWT validation against Cloudflare Access JWKS.
+
+Cloudflare signs Access tokens with RS256. The public keys are published at:
+  https://<team-domain>/cdn-cgi/access/certs
+
+PyJWT's PyJWKClient fetches and caches these automatically.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import jwt
+from jwt import ExpiredSignatureError, InvalidIssuerError, PyJWKClient
+
+from .exceptions import AuthError
+
+
+class TokenValidator:
+    """
+    Validates a Cloudflare Access JWT and returns the decoded payload.
+
+    A single instance should be shared for the lifetime of the application
+    so the JWKS key cache is reused across requests.
+
+    Validates: RS256 signature, issuer (``iss``), expiry (``exp``).
+    The audience (``aud``) claim is present in every Cloudflare JWT but is
+    not checked — all services share the same Zero Trust tenant.
+    """
+
+    def __init__(
+        self,
+        team_domain: str,
+        jwks_client: Optional[PyJWKClient] = None,
+    ) -> None:
+        """
+        Args:
+            team_domain:  Your Cloudflare Zero Trust team domain,
+                          e.g. ``your-org.cloudflareaccess.com``
+                          (without ``https://``).
+            jwks_client:  Optional pre-built ``PyJWKClient`` — primarily for
+                          testing.  When omitted a client is created automatically
+                          pointing at ``<team_domain>/cdn-cgi/access/certs``.
+        """
+        self._team_domain = team_domain.rstrip("/")
+        self._issuer = f"https://{self._team_domain}"
+        certs_url = f"{self._issuer}/cdn-cgi/access/certs"
+
+        # cache_keys=True keeps the JWKS in memory; lifespan=300s is the default.
+        self._jwks_client = jwks_client or PyJWKClient(
+            certs_url, cache_keys=True, max_cached_keys=16
+        )
+
+    def decode(self, token: str) -> Dict[str, Any]:
+        """
+        Verify ``token`` and return the decoded payload.
+
+        Raises:
+            AuthError: If the token is missing, expired, has a bad signature,
+                       wrong issuer, or any other validation failure.
+        """
+        if not token:
+            raise AuthError("No token provided")
+
+        try:
+            signing_key = self._jwks_client.get_signing_key_from_jwt(token)
+        except Exception as exc:
+            raise AuthError(f"Could not fetch signing key: {exc}") from exc
+
+        try:
+            payload: Dict[str, Any] = jwt.decode(
+                token,
+                signing_key.key,
+                algorithms=["RS256"],
+                issuer=self._issuer,
+                options={"verify_aud": False},
+            )
+        except ExpiredSignatureError:
+            raise AuthError("Token has expired") from None
+        except InvalidIssuerError:
+            raise AuthError("Token issuer is not trusted") from None
+        except jwt.PyJWTError as exc:
+            raise AuthError(f"Token validation failed: {exc}") from exc
+
+        return payload

cc_auth-0.1.0.dist-info/METADATA

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: cc-auth
+Version: 0.1.0
+Summary: Cloudflare Access JWT validation + RBAC for Python backends
+Project-URL: Homepage, https://github.com/computacenter-ro/cc-auth
+Project-URL: Repository, https://github.com/computacenter-ro/cc-auth
+Project-URL: Bug Tracker, https://github.com/computacenter-ro/cc-auth/issues
+License: MIT
+Keywords: authentication,cloudflare,cloudflare-access,fastapi,jwt,rbac
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: pyjwt[crypto]>=2.8.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: cryptography>=42.0; extra == 'dev'
+Requires-Dist: fastapi>=0.100.0; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: starlette>=0.27.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
+Requires-Dist: starlette>=0.27.0; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# cc-auth
+
+Python library for validating [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/policies/access/) JWTs and enforcing role-based access control (RBAC) in backend services.
+
+Every service behind a Cloudflare Access Application receives a signed JWT on every request (`CF-Access-Jwt-Assertion` header / `CF_Authorization` cookie). This library:
+
+1. **Validates** the JWT signature against Cloudflare's public keys (JWKS)
+2. **Extracts** identity — email, name, Entra ID group memberships
+3. **Maps** Entra ID groups → application roles
+4. Provides **FastAPI middleware and dependencies** so routes declare their role requirements in one line
+
+---
+
+## Documentation
+
+| Document | Description |
+|---|---|
+| [Azure + Cloudflare group sources](docs/azure-cloudflare-group-sources.md) | Deep dive into the two mechanisms that supply group membership (Microsoft Graph vs ID Token claim), why both exist, and which one `cc-auth` relies on |
+| [ADR-001 — Group claims strategy](docs/adr/001-group-claims-strategy.md) | Architecture Decision Record: why Source A (Support Groups) is the canonical group source, and the trade-offs accepted |
+
+---
+
+## Architecture
+
+```
+Microsoft Entra ID
+      │
+      │  User authenticates (OIDC)
+      ▼
+Cloudflare Zero Trust (Access Application)
+      │
+      │  Issues signed JWT containing:
+      │    { "email": "user@cc.com",
+      │      "groups": ["group-id-1", "group-id-2"],
+      │      "iss": "https://<team-domain>" }
+      │
+      │  JWT travels as header + cookie on every request
+      ▼
+Your FastAPI backend  ◄──── cc-auth validates + maps groups → roles
+      │
+      │  Route reads User.roles for RBAC decisions
+      ▼
+Business logic
+```
+
+**Important:** the backend must always validate the JWT itself. Cloudflare validates at the edge, but if your origin IP is ever reachable directly (bypassing Cloudflare), only your backend's validation stands.
+
+---
+
+## Installation
+
+```bash
+pip install cc-auth
+# or with FastAPI middleware helpers:
+pip install "cc-auth[fastapi]"
+```
+
+Pin a specific version for reproducible production builds:
+```
+cc-auth[fastapi]==0.1.0
+```
+
+---
+
+## Quickstart (FastAPI)
+
+### 1. Enable group claims (one-time, per Zero Trust account)
+
+In Zero Trust → Settings → Authentication → your Azure AD identity provider → **Edit**:
+- Enable **"Support groups"**
+
+This makes Cloudflare include the user's Entra ID group Object IDs in every JWT.
+
+### 2. Add the library to your app
+
+```python
+# main.py
+from fastapi import FastAPI
+from cc_auth import CloudflareAuth
+
+auth = CloudflareAuth.from_env()
+
+app = FastAPI()
+app.add_middleware(auth.middleware(exclude_paths=["/health"]))
+```
+
+No configuration is required to get started. Add `CF_ACCESS_GROUP_MAPPING` when you
+need role-based access control (see [Environment variables](#environment-variables)).
+
+### 3. Use in routes
+
+Most routes need **nothing extra** — the middleware already blocks unauthenticated
+requests. Only add `Depends(...)` when you need the user object or role checks inside
+the handler:
+
+```python
+from cc_auth import User
+
+# Protected automatically by middleware — no Depends needed
+@app.get("/items")
+async def list_items():
+    return [...]
+
+# Need to know who the user is
+@app.get("/me")
+async def me(user: User = Depends(auth.current_user)):
+    return {"email": user.email, "roles": user.roles}
+
+# Restrict to admins only
+@app.delete("/items/{id}")
+async def delete_item(id: str, user: User = Depends(auth.require_role("admin"))):
+    ...
+
+# Restrict to admins or editors
+@app.post("/items")
+async def create_item(user: User = Depends(auth.require_any_role(["admin", "editor"]))):
+    ...
+
+# Excluded from auth — open to anyone
+@app.get("/health")
+async def health():
+    return {"status": "ok"}
+```
+
+---
+
+## Configuration reference
+
+### `CloudflareAuth(team_domain, role_groups=None)`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `team_domain` | `str` | **Yes** | Your Cloudflare Zero Trust team domain, e.g. `your-org.cloudflareaccess.com` |
+| `role_groups` | `dict[str, str]` | No | Map of Entra ID group Object ID → role name |
+
+---
+
+### `User` object
+
+| Field | Type | Description |
+|---|---|---|
+| `sub` | `str` | Cloudflare user identifier (stable across sessions) |
+| `email` | `str` | User's email address |
+| `name` | `str` | Display name (falls back to email) |
+| `groups` | `list[str]` | Entra ID group Object IDs — raw, from JWT |
+| `roles` | `list[str]` | Role names mapped from groups via `role_groups` |
+| `raw` | `dict` | Full decoded JWT payload |
+
+Helper methods:
+- `user.has_role("admin")` → `bool`
+- `user.has_any_role(["admin", "editor"])` → `bool`
+- `user.has_all_roles(["admin", "editor"])` → `bool`
+
+---
+
+## Minimal setup (no RBAC)
+
+If your app only needs SSO (any authenticated user), no environment variables are needed:
+
+```python
+auth = CloudflareAuth.from_env()
+
+app.add_middleware(auth.middleware())   # protects every route
+
+@app.get("/data")
+async def data():
+    return [...]
+
+@app.get("/me")
+async def me(user: User = Depends(auth.current_user)):
+    return {"email": user.email}
+```
+
+---
+
+## Health checks and excluded paths
+
+Skip auth for paths that must be publicly reachable:
+
+```python
+app.add_middleware(auth.middleware(exclude_paths=["/health", "/metrics"]))
+```
+
+Path matching is prefix-based: `/health` excludes `/health`, `/health/live`, `/healthz`, etc.
+
+---
+
+## Environment variables
+
+`CloudflareAuth.from_env()` reads the following environment variables:
+
+| Variable | Description |
+|---|---|
+| `CF_ACCESS_GROUP_MAPPING` | JSON `{"role_name": "group-object-id", ...}`. Role name is the key; group Object ID is the value. The library inverts this internally. |
+| `CF_ACCESS_REQUIRED_GROUPS` | Comma-separated group Object IDs. Each maps to the built-in role `"member"`. Use for simple allow/deny without named roles. |
+| `CF_TEAM_DOMAIN` | **Required for `from_env()`**. Your Cloudflare Zero Trust team domain, e.g. `your-org.cloudflareaccess.com`. |
+
+Both `CF_ACCESS_GROUP_MAPPING` and `CF_ACCESS_REQUIRED_GROUPS` may be set at the same
+time. If the same group Object ID appears in both, `CF_ACCESS_GROUP_MAPPING` wins.
+
+### Simple allow/deny (no named roles)
+
+```bash
+CF_ACCESS_REQUIRED_GROUPS=4fb32c31-b135-43d5-a00e-9e566e6aceff,6543851f-fd97-40e8-b097-ab5a71e44ef2
+```
+
+```python
+auth = CloudflareAuth.from_env()
+
+@app.get("/data")
+async def data(user: User = Depends(auth.require_role("member"))):
+    ...
+```
+
+### Named roles
+
+```bash
+CF_ACCESS_GROUP_MAPPING={"admins":"4fb32c31-...","developers":"6543851f-..."}
+```
+
+```python
+auth = CloudflareAuth.from_env()
+
+@app.delete("/items/{id}")
+async def delete(id: str, user: User = Depends(auth.require_role("admins"))):
+    ...
+```
+
+---
+
+## How it works under the hood
+
+1. On the first request, `PyJWKClient` fetches `https://<team-domain>/cdn-cgi/access/certs` and caches the RSA public keys in memory.
+2. For each request: the token's `kid` header selects the right public key from the cache; `PyJWT` verifies the RS256 signature, `iss`, and `exp`.
+3. Groups are read from the `groups` claim — an array of Entra ID group Object IDs added by Cloudflare when "Support groups" is enabled on the Azure AD identity provider.
+4. Role mapping is a simple dict lookup: O(1) per group.
+
+---
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+---
+
+## Adding to `requirements.txt`
+
+```
+cc-auth[fastapi]==0.1.0
+```
+
+Pin to a specific version for reproducible production builds. Check [PyPI](https://pypi.org/project/cc-auth/) for the latest version.

cc_auth-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+cc_auth/__init__.py,sha256=b0-vQmiFjokGqWHxBXvVBtL2TDT3_UrEhCUzsSrJemg,892
+cc_auth/core.py,sha256=8Huys6QOej0MbceOIWlbTAtMi98MeFpCbuEaYEJRmAY,10493
+cc_auth/exceptions.py,sha256=QOSX5OlSD0PaHUgln_6FXP-WeE88WwQJIqpvKdvGss8,718
+cc_auth/fastapi.py,sha256=yksGmaoVU_ai4roxuHdNnTM5E2vvlnmlL7zlHh-9fg0,3331
+cc_auth/identity.py,sha256=0iYiA05mjO-uoiEvWWRRTioTI66DtgmZtO15t7Th50I,1628
+cc_auth/middleware.py,sha256=1ZCz2_uFcHouag0bAJMrHhyPEQ6qSFbCE0EOWMZB3Fc,2409
+cc_auth/validator.py,sha256=aFHNKqGeVb2iuTjuzZITRmJBRpqWUAV8tL0IcswFKF8,3000
+cc_auth-0.1.0.dist-info/METADATA,sha256=TfOMfPGl1voa6dK-XGMXQbpBIiQBx8NwoBJerNjKmyg,9125
+cc_auth-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+cc_auth-0.1.0.dist-info/RECORD,,

cc_auth-0.1.0.dist-info/WHEEL

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