authfort-service 0.0.2__tar.gz

authfort_service-0.0.2/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

authfort_service-0.0.2/.python-version

@@ -0,0 +1 @@
+3.13

authfort_service-0.0.2/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: authfort-service
+Version: 0.0.2
+Summary: Lightweight JWT verification for AuthFort-powered microservices
+Project-URL: Homepage, https://github.com/bhagyajitjagdev/authfort
+Project-URL: Repository, https://github.com/bhagyajitjagdev/authfort
+Author: Bhagyajit Jagdev
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=46.0.5
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pyjwt[crypto]>=2.11.0
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.104; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# authfort-service
+
+Lightweight JWT verification for microservices powered by AuthFort.
+
+## Install
+
+```bash
+pip install authfort-service[fastapi]
+```
+
+## Quick Start
+
+```python
+from authfort_service import ServiceAuth
+from fastapi import FastAPI, Depends
+
+service = ServiceAuth(
+    jwks_url="https://auth.example.com/.well-known/jwks.json",
+    issuer="authfort",
+)
+
+app = FastAPI()
+
+@app.get("/api/data")
+async def protected(user=Depends(service.current_user)):
+    return {"user_id": user.sub, "roles": user.roles}
+
+@app.get("/api/admin")
+async def admin_only(user=Depends(service.require_role("admin"))):
+    return {"message": "admin access"}
+```
+
+## Features
+
+- JWKS fetching with automatic caching and refresh
+- JWT signature verification (RS256)
+- Token introspection client (optional real-time validation)
+- FastAPI integration (current_user, require_role dependencies)
+- No database required
+
+## With Introspection
+
+```python
+service = ServiceAuth(
+    jwks_url="https://auth.example.com/.well-known/jwks.json",
+    issuer="authfort",
+    introspect_url="https://auth.example.com/auth/introspect",
+    introspect_secret="shared-secret",
+)
+
+# Real-time validation (checks ban status, token version, fresh roles)
+result = await service.introspect(token)
+```
+
+## License
+
+[MIT](../LICENSE)

authfort_service-0.0.2/README.md

@@ -0,0 +1,57 @@
+# authfort-service
+
+Lightweight JWT verification for microservices powered by AuthFort.
+
+## Install
+
+```bash
+pip install authfort-service[fastapi]
+```
+
+## Quick Start
+
+```python
+from authfort_service import ServiceAuth
+from fastapi import FastAPI, Depends
+
+service = ServiceAuth(
+    jwks_url="https://auth.example.com/.well-known/jwks.json",
+    issuer="authfort",
+)
+
+app = FastAPI()
+
+@app.get("/api/data")
+async def protected(user=Depends(service.current_user)):
+    return {"user_id": user.sub, "roles": user.roles}
+
+@app.get("/api/admin")
+async def admin_only(user=Depends(service.require_role("admin"))):
+    return {"message": "admin access"}
+```
+
+## Features
+
+- JWKS fetching with automatic caching and refresh
+- JWT signature verification (RS256)
+- Token introspection client (optional real-time validation)
+- FastAPI integration (current_user, require_role dependencies)
+- No database required
+
+## With Introspection
+
+```python
+service = ServiceAuth(
+    jwks_url="https://auth.example.com/.well-known/jwks.json",
+    issuer="authfort",
+    introspect_url="https://auth.example.com/auth/introspect",
+    introspect_secret="shared-secret",
+)
+
+# Real-time validation (checks ban status, token version, fresh roles)
+result = await service.introspect(token)
+```
+
+## License
+
+[MIT](../LICENSE)

authfort_service-0.0.2/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "authfort-service"
+version = "0.0.2"
+description = "Lightweight JWT verification for AuthFort-powered microservices"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+authors = [{name = "Bhagyajit Jagdev"}]
+dependencies = [
+    "cryptography>=46.0.5",
+    "httpx>=0.28.1",
+    "pyjwt[crypto]>=2.11.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/bhagyajitjagdev/authfort"
+Repository = "https://github.com/bhagyajitjagdev/authfort"
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.104"]
+
+[dependency-groups]
+dev = [
+    "fastapi>=0.129.0",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/authfort_service"]

authfort_service-0.0.2/src/authfort_service/__init__.py

@@ -0,0 +1,9 @@
+"""AuthFort Service — Lightweight JWT verification for microservices."""
+
+__version__ = "0.0.2"
+
+from authfort_service.introspect import IntrospectionResult
+from authfort_service.service_auth import ServiceAuth
+from authfort_service.verifier import TokenPayload, TokenVerificationError
+
+__all__ = ["IntrospectionResult", "ServiceAuth", "TokenPayload", "TokenVerificationError"]

authfort_service-0.0.2/src/authfort_service/integrations/fastapi.py

@@ -0,0 +1,49 @@
+"""FastAPI dependencies for authfort-service."""
+
+from fastapi import Depends, HTTPException, Request
+
+from authfort_service.verifier import JWTVerifier, TokenPayload, TokenVerificationError
+
+
+def create_current_user_dep(verifier: JWTVerifier):
+    """Create a FastAPI dependency that extracts and verifies the JWT."""
+
+    async def current_user(request: Request) -> TokenPayload:
+        auth_header = request.headers.get("Authorization")
+        if not auth_header or not auth_header.startswith("Bearer "):
+            raise HTTPException(
+                status_code=401,
+                detail={"error": "token_missing", "message": "No access token provided"},
+            )
+        token = auth_header[7:]
+
+        try:
+            return await verifier.verify(token)
+        except TokenVerificationError as e:
+            raise HTTPException(
+                status_code=401,
+                detail={"error": e.code, "message": e.message},
+            )
+
+    return current_user
+
+
+def create_require_role_dep(verifier: JWTVerifier, role: str | list[str]):
+    """Create a FastAPI dependency that requires a specific role."""
+    required_roles = [role] if isinstance(role, str) else role
+    current_user_dep = create_current_user_dep(verifier)
+
+    async def check_role(
+        user: TokenPayload = Depends(current_user_dep),
+    ) -> TokenPayload:
+        if not any(r in user.roles for r in required_roles):
+            raise HTTPException(
+                status_code=403,
+                detail={
+                    "error": "insufficient_role",
+                    "message": f"Requires one of: {', '.join(required_roles)}",
+                },
+            )
+        return user
+
+    return check_role

authfort_service-0.0.2/src/authfort_service/introspect.py

@@ -0,0 +1,120 @@
+"""Token introspection client — calls the main AuthFort server for real-time validation.
+
+Use this when you need to check banned status, token version, or fresh roles
+that can't be determined from the JWT alone.
+"""
+
+import logging
+import time
+from dataclasses import dataclass
+
+import httpx
+
+logger = logging.getLogger("authfort_service.introspect")
+
+
+@dataclass(frozen=True, slots=True)
+class IntrospectionResult:
+    """Result from the introspection endpoint."""
+
+    active: bool
+    sub: str | None = None
+    email: str | None = None
+    name: str | None = None
+    roles: list[str] | None = None
+    token_version: int | None = None
+    exp: int | None = None
+    iat: int | None = None
+    iss: str | None = None
+
+
+class IntrospectionClient:
+    """Async HTTP client for the AuthFort introspection endpoint.
+
+    Args:
+        introspect_url: URL of the introspection endpoint.
+        secret: Shared secret for Authorization header (optional).
+        cache_ttl: Cache TTL in seconds (0 = no cache, default).
+        http_timeout: HTTP request timeout in seconds (default 5).
+        fail_open: If True, return inactive on network errors instead of raising.
+    """
+
+    def __init__(
+        self,
+        introspect_url: str,
+        *,
+        secret: str | None = None,
+        cache_ttl: float = 0.0,
+        http_timeout: float = 5.0,
+        fail_open: bool = False,
+    ) -> None:
+        self._introspect_url = introspect_url
+        self._secret = secret
+        self._cache_ttl = cache_ttl
+        self._http_timeout = http_timeout
+        self._fail_open = fail_open
+        self._cache: dict[str, tuple[IntrospectionResult, float]] = {}
+
+    async def introspect(self, token: str) -> IntrospectionResult:
+        """Introspect a token via the auth server.
+
+        Returns:
+            IntrospectionResult with active=True/False.
+
+        Raises:
+            httpx.HTTPError: If auth server unreachable and fail_open is False.
+        """
+        if self._cache_ttl > 0:
+            cached = self._cache.get(token)
+            if cached is not None:
+                result, cached_at = cached
+                if (time.monotonic() - cached_at) < self._cache_ttl:
+                    return result
+
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if self._secret:
+            headers["Authorization"] = f"Bearer {self._secret}"
+
+        try:
+            async with httpx.AsyncClient(timeout=self._http_timeout) as client:
+                response = await client.post(
+                    self._introspect_url,
+                    json={"token": token},
+                    headers=headers,
+                )
+                response.raise_for_status()
+                data = response.json()
+        except Exception:
+            if self._fail_open:
+                logger.warning(
+                    "Introspection failed for %s, returning inactive",
+                    self._introspect_url,
+                )
+                return IntrospectionResult(active=False)
+            raise
+
+        result = IntrospectionResult(
+            active=data.get("active", False),
+            sub=data.get("sub"),
+            email=data.get("email"),
+            name=data.get("name"),
+            roles=data.get("roles"),
+            token_version=data.get("token_version"),
+            exp=data.get("exp"),
+            iat=data.get("iat"),
+            iss=data.get("iss"),
+        )
+
+        if self._cache_ttl > 0:
+            self._cache[token] = (result, time.monotonic())
+            if len(self._cache) > 1000:
+                self._evict_stale()
+
+        return result
+
+    def _evict_stale(self) -> None:
+        """Remove expired entries from the cache."""
+        now = time.monotonic()
+        stale = [k for k, (_, t) in self._cache.items() if (now - t) > self._cache_ttl]
+        for k in stale:
+            del self._cache[k]

authfort_service-0.0.2/src/authfort_service/jwks.py

@@ -0,0 +1,119 @@
+"""JWKS fetcher and cache — fetches public keys from the auth server.
+
+Features:
+- TTL-based cache (configurable, default 1 hour)
+- Auto-refresh on unknown kid (key rotation)
+- Rate-limited refetch (max once per min_refetch_interval)
+- Async-safe via asyncio.Lock
+"""
+
+import asyncio
+import logging
+import time
+from dataclasses import dataclass, field
+
+import httpx
+from jwt import PyJWK
+
+logger = logging.getLogger("authfort_service.jwks")
+
+
+@dataclass
+class CachedJWKS:
+    """In-memory cache of JWKS keys."""
+
+    keys: dict[str, PyJWK] = field(default_factory=dict)
+    fetched_at: float = 0.0
+
+
+class JWKSFetcher:
+    """Fetches and caches JWKS public keys from the auth server.
+
+    Args:
+        jwks_url: URL of the JWKS endpoint.
+        cache_ttl: How long to cache keys in seconds (default 3600 = 1 hour).
+        min_refetch_interval: Minimum seconds between fetch attempts (default 30).
+        http_timeout: HTTP request timeout in seconds (default 10).
+    """
+
+    def __init__(
+        self,
+        jwks_url: str,
+        *,
+        cache_ttl: float = 3600.0,
+        min_refetch_interval: float = 30.0,
+        http_timeout: float = 10.0,
+        _transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._jwks_url = jwks_url
+        self._cache_ttl = cache_ttl
+        self._min_refetch_interval = min_refetch_interval
+        self._http_timeout = http_timeout
+        self._transport = _transport
+        self._cache = CachedJWKS()
+        self._lock = asyncio.Lock()
+        self._last_fetch_attempt: float = float("-inf")
+
+    async def get_key(self, kid: str) -> PyJWK | None:
+        """Get a public key by kid. Refreshes cache if stale."""
+        key = self._cache.keys.get(kid)
+        if key is not None and not self._is_cache_stale():
+            return key
+        await self._maybe_refresh()
+        return self._cache.keys.get(kid)
+
+    async def get_key_or_refresh(self, kid: str) -> PyJWK | None:
+        """Get a key, forcing a refresh if kid is unknown (key rotation scenario)."""
+        key = self._cache.keys.get(kid)
+        if key is not None:
+            return key
+        await self._maybe_refresh(force=True)
+        return self._cache.keys.get(kid)
+
+    def _is_cache_stale(self) -> bool:
+        if self._cache.fetched_at == 0.0:
+            return True
+        return (time.monotonic() - self._cache.fetched_at) > self._cache_ttl
+
+    async def _maybe_refresh(self, *, force: bool = False) -> None:
+        """Refresh the JWKS cache, respecting rate limits."""
+        now = time.monotonic()
+        if not force and not self._is_cache_stale():
+            return
+        if (now - self._last_fetch_attempt) < self._min_refetch_interval:
+            return
+
+        async with self._lock:
+            now = time.monotonic()
+            if (now - self._last_fetch_attempt) < self._min_refetch_interval:
+                return
+            self._last_fetch_attempt = now
+            try:
+                await self._fetch()
+            except Exception:
+                logger.exception("Failed to fetch JWKS from %s", self._jwks_url)
+
+    async def _fetch(self) -> None:
+        """Fetch JWKS from the server and update cache."""
+        kwargs: dict = {"timeout": self._http_timeout}
+        if self._transport is not None:
+            kwargs["transport"] = self._transport
+        async with httpx.AsyncClient(**kwargs) as client:
+            response = await client.get(self._jwks_url)
+            response.raise_for_status()
+            jwks_data = response.json()
+
+        new_keys: dict[str, PyJWK] = {}
+        for key_data in jwks_data.get("keys", []):
+            try:
+                kid = key_data.get("kid")
+                if kid:
+                    new_keys[kid] = PyJWK(key_data)
+            except Exception:
+                logger.warning("Failed to parse JWK with kid=%s", key_data.get("kid"))
+
+        self._cache = CachedJWKS(
+            keys=new_keys,
+            fetched_at=time.monotonic(),
+        )
+        logger.debug("JWKS refreshed: %d keys loaded", len(new_keys))

authfort_service-0.0.2/src/authfort_service/service_auth.py

@@ -0,0 +1,102 @@
+"""ServiceAuth — main entry point for authfort-service.
+
+Mirrors AuthFort's API style with .current_user and .require_role() dependencies.
+No database needed — verifies JWTs using cached JWKS public keys.
+"""
+
+from authfort_service.introspect import IntrospectionClient, IntrospectionResult
+from authfort_service.jwks import JWKSFetcher
+from authfort_service.verifier import JWTVerifier, TokenPayload, TokenVerificationError
+
+
+class ServiceAuth:
+    """Lightweight JWT verifier for microservices.
+
+    Verifies AuthFort-issued JWTs using JWKS public keys.
+    Optionally introspects tokens for real-time checks (banned, version mismatch).
+
+    Args:
+        jwks_url: URL of the AuthFort JWKS endpoint.
+        issuer: Expected JWT issuer claim (default "authfort").
+        algorithms: Allowed JWT algorithms (default ["RS256"]).
+        jwks_cache_ttl: How long to cache JWKS keys in seconds (default 3600).
+        introspect_url: URL of the introspection endpoint (optional).
+        introspect_secret: Shared secret for introspection auth (optional).
+        introspect_cache_ttl: Cache TTL for introspection results (default 0 = no cache).
+    """
+
+    def __init__(
+        self,
+        jwks_url: str,
+        *,
+        issuer: str = "authfort",
+        algorithms: list[str] | None = None,
+        jwks_cache_ttl: float = 3600.0,
+        introspect_url: str | None = None,
+        introspect_secret: str | None = None,
+        introspect_cache_ttl: float = 0.0,
+    ) -> None:
+        self._jwks_fetcher = JWKSFetcher(jwks_url, cache_ttl=jwks_cache_ttl)
+        self._verifier = JWTVerifier(
+            self._jwks_fetcher, issuer=issuer, algorithms=algorithms,
+        )
+        self._introspect_client: IntrospectionClient | None = None
+        if introspect_url is not None:
+            self._introspect_client = IntrospectionClient(
+                introspect_url,
+                secret=introspect_secret,
+                cache_ttl=introspect_cache_ttl,
+                fail_open=True,
+            )
+        self._current_user_dep = None
+
+    async def verify_token(self, token: str) -> TokenPayload:
+        """Verify a JWT and return the decoded payload (JWKS-only, no introspection).
+
+        Raises:
+            TokenVerificationError: If verification fails.
+        """
+        return await self._verifier.verify(token)
+
+    async def introspect(self, token: str) -> IntrospectionResult:
+        """Introspect a token via the auth server (real-time check).
+
+        Raises:
+            RuntimeError: If introspection is not configured.
+        """
+        if self._introspect_client is None:
+            raise RuntimeError(
+                "Introspection not configured. Pass introspect_url to ServiceAuth()."
+            )
+        return await self._introspect_client.introspect(token)
+
+    @property
+    def current_user(self):
+        """FastAPI dependency: get the current authenticated user from JWT.
+
+        Uses JWKS-only verification (fast, no network call to auth server).
+
+        Usage:
+            service_auth = ServiceAuth(jwks_url="...")
+
+            @app.get("/profile")
+            async def profile(user=Depends(service_auth.current_user)):
+                print(user.email)
+        """
+        if self._current_user_dep is None:
+            from authfort_service.integrations.fastapi import create_current_user_dep
+
+            self._current_user_dep = create_current_user_dep(self._verifier)
+        return self._current_user_dep
+
+    def require_role(self, role: str | list[str]):
+        """FastAPI dependency factory: require a specific role.
+
+        Usage:
+            @app.get("/admin")
+            async def admin(user=Depends(service_auth.require_role("admin"))):
+                ...
+        """
+        from authfort_service.integrations.fastapi import create_require_role_dep
+
+        return create_require_role_dep(self._verifier, role)

authfort_service-0.0.2/src/authfort_service/verifier.py

@@ -0,0 +1,104 @@
+"""JWT verification using JWKS public keys — local verification, no DB needed."""
+
+import logging
+from dataclasses import dataclass
+
+import jwt
+
+from authfort_service.jwks import JWKSFetcher
+
+logger = logging.getLogger("authfort_service.verifier")
+
+
+class TokenVerificationError(Exception):
+    """Raised when JWT verification fails."""
+
+    def __init__(self, message: str, code: str):
+        self.message = message
+        self.code = code
+        super().__init__(message)
+
+
+@dataclass(frozen=True, slots=True)
+class TokenPayload:
+    """Decoded JWT payload — the user identity from a verified token."""
+
+    sub: str
+    email: str
+    name: str | None
+    roles: list[str]
+    token_version: int
+    exp: int
+    iat: int
+    iss: str
+
+
+class JWTVerifier:
+    """Verifies JWT access tokens using JWKS public keys.
+
+    No database needed — pure cryptographic verification using cached public keys.
+
+    Args:
+        jwks_fetcher: The JWKS fetcher for key lookup.
+        issuer: Expected JWT issuer claim (default "authfort").
+        algorithms: Allowed JWT algorithms (default ["RS256"]).
+    """
+
+    def __init__(
+        self,
+        jwks_fetcher: JWKSFetcher,
+        *,
+        issuer: str = "authfort",
+        algorithms: list[str] | None = None,
+    ) -> None:
+        self._fetcher = jwks_fetcher
+        self._issuer = issuer
+        self._algorithms = algorithms or ["RS256"]
+
+    async def verify(self, token: str) -> TokenPayload:
+        """Verify a JWT and return the decoded payload.
+
+        Checks: signature, expiration, issuer, required claims.
+        On unknown kid, triggers JWKS refresh (handles key rotation).
+
+        Raises:
+            TokenVerificationError: If verification fails.
+        """
+        try:
+            header = jwt.get_unverified_header(token)
+        except jwt.InvalidTokenError:
+            raise TokenVerificationError("Malformed token", "token_invalid")
+
+        kid = header.get("kid")
+        if not kid:
+            raise TokenVerificationError("Token missing kid header", "token_invalid")
+
+        jwk = await self._fetcher.get_key_or_refresh(kid)
+        if jwk is None:
+            raise TokenVerificationError("Unknown signing key", "token_invalid")
+
+        try:
+            payload = jwt.decode(
+                token,
+                jwk.key,
+                algorithms=self._algorithms,
+                issuer=self._issuer,
+                options={"require": ["sub", "email", "roles", "ver", "exp", "iat", "iss"]},
+            )
+        except jwt.ExpiredSignatureError:
+            raise TokenVerificationError("Token has expired", "token_expired")
+        except jwt.InvalidIssuerError:
+            raise TokenVerificationError("Invalid issuer", "token_invalid")
+        except jwt.InvalidTokenError as e:
+            raise TokenVerificationError(f"Invalid token: {e}", "token_invalid")
+
+        return TokenPayload(
+            sub=payload["sub"],
+            email=payload["email"],
+            name=payload.get("name"),
+            roles=payload["roles"],
+            token_version=payload["ver"],
+            exp=payload["exp"],
+            iat=payload["iat"],
+            iss=payload["iss"],
+        )

authfort_service-0.0.2/tests/conftest.py

@@ -0,0 +1,95 @@
+"""Test fixtures for authfort-service tests.
+
+All tests are DB-free — they generate RSA keys, create JWTs manually,
+and mock JWKS responses using httpx MockTransport.
+"""
+
+import json
+import uuid
+from datetime import UTC, datetime, timedelta
+
+import jwt
+import pytest
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+
+pytestmark = pytest.mark.asyncio
+
+
+@pytest.fixture
+def rsa_key_pair():
+    """Generate a test RSA key pair."""
+    private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+    private_pem = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    ).decode("utf-8")
+    public_pem = private_key.public_key().public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    ).decode("utf-8")
+    return private_pem, public_pem
+
+
+@pytest.fixture
+def test_kid():
+    return f"test-key-{uuid.uuid4().hex[:8]}"
+
+
+@pytest.fixture
+def jwk_from_public_key(rsa_key_pair, test_kid):
+    """Convert the test public key to JWK format."""
+    import base64
+
+    from cryptography.hazmat.primitives.serialization import load_pem_public_key
+
+    _, public_pem = rsa_key_pair
+    public_key = load_pem_public_key(public_pem.encode("utf-8"))
+    public_numbers = public_key.public_numbers()
+
+    def _int_to_b64url(value: int) -> str:
+        byte_length = (value.bit_length() + 7) // 8
+        value_bytes = value.to_bytes(byte_length, byteorder="big")
+        return base64.urlsafe_b64encode(value_bytes).rstrip(b"=").decode("ascii")
+
+    return {
+        "kty": "RSA",
+        "kid": test_kid,
+        "use": "sig",
+        "alg": "RS256",
+        "n": _int_to_b64url(public_numbers.n),
+        "e": _int_to_b64url(public_numbers.e),
+    }
+
+
+@pytest.fixture
+def jwks_response(jwk_from_public_key):
+    """A JWKS response body with one key."""
+    return {"keys": [jwk_from_public_key]}
+
+
+def create_test_token(
+    private_key_pem: str,
+    kid: str,
+    *,
+    user_id: str | None = None,
+    email: str = "test@example.com",
+    roles: list[str] | None = None,
+    token_version: int = 1,
+    issuer: str = "authfort",
+    expires_in: int = 900,
+) -> str:
+    """Create a test JWT signed with the given private key."""
+    now = datetime.now(UTC)
+    payload = {
+        "sub": user_id or str(uuid.uuid4()),
+        "email": email,
+        "name": "Test User",
+        "roles": roles or [],
+        "ver": token_version,
+        "iat": now,
+        "exp": now + timedelta(seconds=expires_in),
+        "iss": issuer,
+    }
+    return jwt.encode(payload, private_key_pem, algorithm="RS256", headers={"kid": kid})

authfort_service-0.0.2/tests/test_introspect_client.py

@@ -0,0 +1,138 @@
+"""Tests for the introspection client — HTTP calls, caching, and error handling."""
+
+import httpx
+import pytest
+
+from authfort_service.introspect import IntrospectionClient, IntrospectionResult
+
+pytestmark = pytest.mark.asyncio
+
+
+def _mock_introspect(response_data: dict, *, status_code: int = 200):
+    """Create mock transport for introspection endpoint."""
+    captured_requests = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured_requests.append(request)
+        return httpx.Response(status_code, json=response_data)
+
+    return handler, captured_requests
+
+
+class TestIntrospectionClient:
+    async def test_introspect_active_token(self, monkeypatch):
+        response = {
+            "active": True, "sub": "user-123", "email": "test@example.com",
+            "roles": ["admin"], "token_version": 1, "exp": 99999, "iat": 11111,
+            "iss": "authfort",
+        }
+        handler, _ = _mock_introspect(response)
+
+        original_init = httpx.AsyncClient.__init__
+
+        def patched_init(self_client, **kwargs):
+            kwargs["transport"] = httpx.MockTransport(handler)
+            original_init(self_client, **kwargs)
+
+        monkeypatch.setattr(httpx.AsyncClient, "__init__", patched_init)
+
+        client = IntrospectionClient("http://test/auth/introspect")
+        result = await client.introspect("some-token")
+
+        assert isinstance(result, IntrospectionResult)
+        assert result.active is True
+        assert result.email == "test@example.com"
+        assert result.roles == ["admin"]
+
+    async def test_introspect_inactive_token(self, monkeypatch):
+        handler, _ = _mock_introspect({"active": False})
+
+        original_init = httpx.AsyncClient.__init__
+
+        def patched_init(self_client, **kwargs):
+            kwargs["transport"] = httpx.MockTransport(handler)
+            original_init(self_client, **kwargs)
+
+        monkeypatch.setattr(httpx.AsyncClient, "__init__", patched_init)
+
+        client = IntrospectionClient("http://test/auth/introspect")
+        result = await client.introspect("bad-token")
+        assert result.active is False
+
+    async def test_introspect_sends_secret(self, monkeypatch):
+        handler, captured = _mock_introspect({"active": True})
+
+        original_init = httpx.AsyncClient.__init__
+
+        def patched_init(self_client, **kwargs):
+            kwargs["transport"] = httpx.MockTransport(handler)
+            original_init(self_client, **kwargs)
+
+        monkeypatch.setattr(httpx.AsyncClient, "__init__", patched_init)
+
+        client = IntrospectionClient(
+            "http://test/auth/introspect", secret="my-secret",
+        )
+        await client.introspect("token")
+
+        assert len(captured) == 1
+        assert captured[0].headers["Authorization"] == "Bearer my-secret"
+
+    async def test_introspect_cache(self, monkeypatch):
+        call_count = {"n": 0}
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            call_count["n"] += 1
+            return httpx.Response(200, json={"active": True, "email": "test@example.com"})
+
+        original_init = httpx.AsyncClient.__init__
+
+        def patched_init(self_client, **kwargs):
+            kwargs["transport"] = httpx.MockTransport(handler)
+            original_init(self_client, **kwargs)
+
+        monkeypatch.setattr(httpx.AsyncClient, "__init__", patched_init)
+
+        client = IntrospectionClient(
+            "http://test/auth/introspect", cache_ttl=60,
+        )
+        await client.introspect("token-1")
+        await client.introspect("token-1")  # Cached
+        await client.introspect("token-1")  # Cached
+        assert call_count["n"] == 1
+
+    async def test_network_error_fail_open(self, monkeypatch):
+        def error_handler(request: httpx.Request) -> httpx.Response:
+            raise httpx.ConnectError("connection refused")
+
+        original_init = httpx.AsyncClient.__init__
+
+        def patched_init(self_client, **kwargs):
+            kwargs["transport"] = httpx.MockTransport(error_handler)
+            original_init(self_client, **kwargs)
+
+        monkeypatch.setattr(httpx.AsyncClient, "__init__", patched_init)
+
+        client = IntrospectionClient(
+            "http://test/auth/introspect", fail_open=True,
+        )
+        result = await client.introspect("token")
+        assert result.active is False
+
+    async def test_network_error_fail_closed(self, monkeypatch):
+        def error_handler(request: httpx.Request) -> httpx.Response:
+            raise httpx.ConnectError("connection refused")
+
+        original_init = httpx.AsyncClient.__init__
+
+        def patched_init(self_client, **kwargs):
+            kwargs["transport"] = httpx.MockTransport(error_handler)
+            original_init(self_client, **kwargs)
+
+        monkeypatch.setattr(httpx.AsyncClient, "__init__", patched_init)
+
+        client = IntrospectionClient(
+            "http://test/auth/introspect", fail_open=False,
+        )
+        with pytest.raises(httpx.ConnectError):
+            await client.introspect("token")

authfort_service-0.0.2/tests/test_jwks_fetcher.py

@@ -0,0 +1,115 @@
+"""Tests for the JWKS fetcher — caching, refresh, and error handling."""
+
+import logging
+
+import httpx
+import pytest
+
+from authfort_service.jwks import JWKSFetcher
+
+pytestmark = pytest.mark.asyncio
+
+
+def _make_mock_transport(jwks_response: dict, *, status_code: int = 200):
+    """Create an httpx MockTransport that returns the given JWKS response."""
+    call_count = {"n": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        call_count["n"] += 1
+        return httpx.Response(status_code, json=jwks_response)
+
+    return httpx.MockTransport(handler), call_count
+
+
+class TestJWKSFetcher:
+    async def test_fetch_and_cache_keys(self, jwks_response, test_kid):
+        transport, call_count = _make_mock_transport(jwks_response)
+        fetcher = JWKSFetcher(
+            "http://test/.well-known/jwks.json",
+            cache_ttl=3600,
+            _transport=transport,
+        )
+
+        key = await fetcher.get_key(test_kid)
+        assert key is not None
+        assert call_count["n"] == 1
+
+    async def test_cache_prevents_refetch(self, jwks_response, test_kid):
+        transport, call_count = _make_mock_transport(jwks_response)
+        fetcher = JWKSFetcher(
+            "http://test/.well-known/jwks.json",
+            cache_ttl=3600,
+            _transport=transport,
+        )
+
+        await fetcher.get_key(test_kid)
+        await fetcher.get_key(test_kid)
+        await fetcher.get_key(test_kid)
+        assert call_count["n"] == 1  # Only one fetch
+
+    async def test_unknown_kid_triggers_refresh(self, jwks_response, test_kid):
+        transport, call_count = _make_mock_transport(jwks_response)
+        fetcher = JWKSFetcher(
+            "http://test/.well-known/jwks.json",
+            cache_ttl=3600,
+            min_refetch_interval=0,
+            _transport=transport,
+        )
+
+        await fetcher.get_key(test_kid)
+        result = await fetcher.get_key_or_refresh("unknown-kid")
+        assert result is None
+        assert call_count["n"] == 2  # Second fetch attempted
+
+    async def test_rate_limiting(self, jwks_response, test_kid):
+        transport, call_count = _make_mock_transport(jwks_response)
+        fetcher = JWKSFetcher(
+            "http://test/.well-known/jwks.json",
+            cache_ttl=0,  # Always stale
+            min_refetch_interval=60,  # Rate limit 60s
+            _transport=transport,
+        )
+
+        await fetcher.get_key(test_kid)  # First fetch
+        await fetcher.get_key(test_kid)  # Rate limited, no fetch
+        assert call_count["n"] == 1
+
+    async def test_fetch_failure_logged(self, test_kid, caplog):
+        def error_handler(request: httpx.Request) -> httpx.Response:
+            raise httpx.ConnectError("connection refused")
+
+        transport = httpx.MockTransport(error_handler)
+        fetcher = JWKSFetcher(
+            "http://test/.well-known/jwks.json",
+            _transport=transport,
+        )
+
+        with caplog.at_level(logging.ERROR, logger="authfort_service.jwks"):
+            result = await fetcher.get_key(test_kid)
+        assert result is None
+        assert "Failed to fetch JWKS" in caplog.text
+
+    async def test_malformed_jwk_skipped(self, test_kid):
+        jwks_with_bad_key = {
+            "keys": [
+                {"kty": "invalid", "kid": "bad-key"},
+            ]
+        }
+        transport, _ = _make_mock_transport(jwks_with_bad_key)
+        fetcher = JWKSFetcher(
+            "http://test/.well-known/jwks.json",
+            _transport=transport,
+        )
+
+        result = await fetcher.get_key("bad-key")
+        assert result is None  # Bad key should be skipped
+
+    async def test_empty_jwks_response(self):
+        transport, _ = _make_mock_transport({"keys": []})
+        fetcher = JWKSFetcher(
+            "http://test/.well-known/jwks.json",
+            _transport=transport,
+        )
+
+        result = await fetcher.get_key("any-kid")
+        assert result is None

authfort_service-0.0.2/tests/test_service_auth.py

@@ -0,0 +1,102 @@
+"""Tests for ServiceAuth — main entry point, FastAPI integration."""
+
+import httpx
+import pytest
+from fastapi import Depends, FastAPI
+from httpx import ASGITransport, AsyncClient
+
+from authfort_service import ServiceAuth, TokenPayload, TokenVerificationError
+from conftest import create_test_token
+
+pytestmark = pytest.mark.asyncio
+
+
+def _patch_fetcher(monkeypatch, jwks_response):
+    """Patch httpx.AsyncClient to return mock JWKS response.
+
+    Only patches clients that don't already have an ASGITransport
+    (so the test's own ASGI test client isn't affected).
+    """
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json=jwks_response)
+
+    original_init = httpx.AsyncClient.__init__
+
+    def patched_init(self_client, **kwargs):
+        if not isinstance(kwargs.get("transport"), ASGITransport):
+            kwargs["transport"] = httpx.MockTransport(handler)
+        original_init(self_client, **kwargs)
+
+    monkeypatch.setattr(httpx.AsyncClient, "__init__", patched_init)
+
+
+class TestServiceAuth:
+    async def test_verify_token(self, rsa_key_pair, test_kid, jwks_response, monkeypatch):
+        _patch_fetcher(monkeypatch, jwks_response)
+        private_pem, _ = rsa_key_pair
+
+        sa = ServiceAuth(jwks_url="http://test/.well-known/jwks.json")
+        token = create_test_token(private_pem, test_kid, email="test@example.com")
+        payload = await sa.verify_token(token)
+
+        assert isinstance(payload, TokenPayload)
+        assert payload.email == "test@example.com"
+
+    async def test_introspect_not_configured(self):
+        sa = ServiceAuth(jwks_url="http://test/.well-known/jwks.json")
+        with pytest.raises(RuntimeError, match="Introspection not configured"):
+            await sa.introspect("token")
+
+    async def test_current_user_dep(self, rsa_key_pair, test_kid, jwks_response, monkeypatch):
+        _patch_fetcher(monkeypatch, jwks_response)
+        private_pem, _ = rsa_key_pair
+
+        sa = ServiceAuth(jwks_url="http://test/.well-known/jwks.json")
+        token = create_test_token(private_pem, test_kid, email="user@example.com", roles=["user"])
+
+        app = FastAPI()
+
+        @app.get("/profile")
+        async def profile(user=Depends(sa.current_user)):
+            return {"email": user.email, "roles": user.roles}
+
+        async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
+            resp = await client.get("/profile", headers={"Authorization": f"Bearer {token}"})
+            assert resp.status_code == 200
+            assert resp.json()["email"] == "user@example.com"
+
+    async def test_require_role(self, rsa_key_pair, test_kid, jwks_response, monkeypatch):
+        _patch_fetcher(monkeypatch, jwks_response)
+        private_pem, _ = rsa_key_pair
+
+        sa = ServiceAuth(jwks_url="http://test/.well-known/jwks.json")
+
+        app = FastAPI()
+
+        @app.get("/admin")
+        async def admin(user=Depends(sa.require_role("admin"))):
+            return {"message": "admin access"}
+
+        admin_token = create_test_token(private_pem, test_kid, roles=["admin"])
+        user_token = create_test_token(private_pem, test_kid, roles=["user"])
+
+        async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
+            resp = await client.get("/admin", headers={"Authorization": f"Bearer {admin_token}"})
+            assert resp.status_code == 200
+
+            resp = await client.get("/admin", headers={"Authorization": f"Bearer {user_token}"})
+            assert resp.status_code == 403
+
+    async def test_current_user_no_token(self, rsa_key_pair, test_kid, jwks_response, monkeypatch):
+        _patch_fetcher(monkeypatch, jwks_response)
+        sa = ServiceAuth(jwks_url="http://test/.well-known/jwks.json")
+
+        app = FastAPI()
+
+        @app.get("/profile")
+        async def profile(user=Depends(sa.current_user)):
+            return {"email": user.email}
+
+        async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
+            resp = await client.get("/profile")
+            assert resp.status_code == 401

authfort_service-0.0.2/tests/test_verifier.py

@@ -0,0 +1,129 @@
+"""Tests for the JWT verifier — token verification using JWKS keys."""
+
+import time
+
+import httpx
+import pytest
+
+from authfort_service.jwks import JWKSFetcher
+from authfort_service.verifier import JWTVerifier, TokenPayload, TokenVerificationError
+from conftest import create_test_token
+
+pytestmark = pytest.mark.asyncio
+
+
+def _patch_fetcher(monkeypatch, jwks_response):
+    """Patch httpx.AsyncClient to return mock JWKS response."""
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json=jwks_response)
+
+    original_init = httpx.AsyncClient.__init__
+
+    def patched_init(self_client, **kwargs):
+        kwargs["transport"] = httpx.MockTransport(handler)
+        original_init(self_client, **kwargs)
+
+    monkeypatch.setattr(httpx.AsyncClient, "__init__", patched_init)
+
+
+class TestJWTVerifier:
+    async def test_verify_valid_token(self, rsa_key_pair, test_kid, jwks_response, monkeypatch):
+        _patch_fetcher(monkeypatch, jwks_response)
+        private_pem, _ = rsa_key_pair
+        fetcher = JWKSFetcher("http://test/.well-known/jwks.json")
+        verifier = JWTVerifier(fetcher)
+
+        token = create_test_token(private_pem, test_kid, email="user@example.com", roles=["admin"])
+        payload = await verifier.verify(token)
+
+        assert isinstance(payload, TokenPayload)
+        assert payload.email == "user@example.com"
+        assert payload.roles == ["admin"]
+        assert payload.name == "Test User"
+        assert payload.iss == "authfort"
+
+    async def test_verify_expired_token(self, rsa_key_pair, test_kid, jwks_response, monkeypatch):
+        _patch_fetcher(monkeypatch, jwks_response)
+        private_pem, _ = rsa_key_pair
+        fetcher = JWKSFetcher("http://test/.well-known/jwks.json")
+        verifier = JWTVerifier(fetcher)
+
+        token = create_test_token(private_pem, test_kid, expires_in=-10)
+
+        with pytest.raises(TokenVerificationError, match="expired"):
+            await verifier.verify(token)
+
+    async def test_verify_wrong_issuer(self, rsa_key_pair, test_kid, jwks_response, monkeypatch):
+        _patch_fetcher(monkeypatch, jwks_response)
+        private_pem, _ = rsa_key_pair
+        fetcher = JWKSFetcher("http://test/.well-known/jwks.json")
+        verifier = JWTVerifier(fetcher, issuer="expected-issuer")
+
+        token = create_test_token(private_pem, test_kid, issuer="wrong-issuer")
+
+        with pytest.raises(TokenVerificationError, match="Invalid"):
+            await verifier.verify(token)
+
+    async def test_verify_missing_kid(self, monkeypatch, jwks_response):
+        _patch_fetcher(monkeypatch, jwks_response)
+        fetcher = JWKSFetcher("http://test/.well-known/jwks.json")
+        verifier = JWTVerifier(fetcher)
+
+        # Create a JWT without kid in header
+        import jwt
+        from datetime import UTC, datetime, timedelta
+
+        now = datetime.now(UTC)
+        token = jwt.encode(
+            {"sub": "user", "email": "test@example.com", "roles": [], "ver": 1,
+             "iat": now, "exp": now + timedelta(seconds=900), "iss": "authfort"},
+            "secret", algorithm="HS256",
+        )
+
+        with pytest.raises(TokenVerificationError):
+            await verifier.verify(token)
+
+    async def test_verify_unknown_kid(self, rsa_key_pair, jwks_response, monkeypatch):
+        _patch_fetcher(monkeypatch, jwks_response)
+        private_pem, _ = rsa_key_pair
+        fetcher = JWKSFetcher(
+            "http://test/.well-known/jwks.json", min_refetch_interval=0,
+        )
+        verifier = JWTVerifier(fetcher)
+
+        token = create_test_token(private_pem, "unknown-kid-12345")
+
+        with pytest.raises(TokenVerificationError, match="Unknown signing key"):
+            await verifier.verify(token)
+
+    async def test_verify_malformed_token(self, monkeypatch, jwks_response):
+        _patch_fetcher(monkeypatch, jwks_response)
+        fetcher = JWKSFetcher("http://test/.well-known/jwks.json")
+        verifier = JWTVerifier(fetcher)
+
+        with pytest.raises(TokenVerificationError, match="Malformed"):
+            await verifier.verify("not.a.valid.token")
+
+    async def test_verify_returns_all_fields(self, rsa_key_pair, test_kid, jwks_response, monkeypatch):
+        _patch_fetcher(monkeypatch, jwks_response)
+        private_pem, _ = rsa_key_pair
+        fetcher = JWKSFetcher("http://test/.well-known/jwks.json")
+        verifier = JWTVerifier(fetcher)
+
+        user_id = "550e8400-e29b-41d4-a716-446655440000"
+        token = create_test_token(
+            private_pem, test_kid,
+            user_id=user_id,
+            email="hello@example.com",
+            roles=["admin", "editor"],
+            token_version=3,
+        )
+        payload = await verifier.verify(token)
+
+        assert payload.sub == user_id
+        assert payload.email == "hello@example.com"
+        assert payload.roles == ["admin", "editor"]
+        assert payload.token_version == 3
+        assert payload.iss == "authfort"
+        assert isinstance(payload.exp, int)
+        assert isinstance(payload.iat, int)