open-shield-python 0.1.0__py3-none-any.whl

open_shield/adapters/__init__.py

@@ -0,0 +1,5 @@
+from .config import OpenShieldConfig
+from .key_provider import OIDCDiscoKeyProvider
+from .token_validator import PyJWTValidator
+
+__all__ = ["OIDCDiscoKeyProvider", "OpenShieldConfig", "PyJWTValidator"]

open_shield/adapters/config.py

@@ -0,0 +1,26 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class OpenShieldConfig(BaseSettings):
+    """
+    Configuration for Open Shield SDK.
+    Loads settings from environment variables (OPEN_SHIELD_prefix).
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="OPEN_SHIELD_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    ISSUER_URL: str
+    AUDIENCE: str | None = None
+    ALGORITHMS: list[str] = ["RS256"]
+
+    # Authorization defaults
+    REQUIRE_SCOPES: bool = True
+    REQUIRE_ROLES: bool = False
+
+    # Tenant extraction
+    TENANT_ID_CLAIM: str = "tid"

open_shield/adapters/key_provider.py

@@ -0,0 +1,109 @@
+from typing import Any
+
+import httpx
+
+from open_shield.domain.exceptions import ConfigurationError, OpenShieldError
+from open_shield.domain.ports import KeyProviderPort
+
+
+class OIDCDiscoKeyProvider(KeyProviderPort):
+    """
+    Adapter that fetches JWKS from an OIDC provider's well-known configuration.
+    Features:
+    - Automatic discovery of jwks_uri
+    - Key caching (simple in-memory for MVP)
+    - Key rotation support (refresh on miss)
+    """
+
+    def __init__(self, issuer_url: str):
+        self.issuer_url = issuer_url.rstrip("/")
+        self._jwks_uri: str | None = None
+        self._keys: dict[str, Any] = {}
+        self._client = httpx.Client()  # Use sync client for simplicity in core logic
+
+    def get_key(self, kid: str) -> Any:
+        if kid not in self._keys:
+            self._refresh_keys()
+
+        if kid not in self._keys:
+            # Try one more time, force refresh
+            self._refresh_keys()
+
+        if kid not in self._keys:
+            raise OpenShieldError(
+                f"Key ID {kid} not found in JWKS from {self.issuer_url}"
+            )
+
+        return self._keys[kid]
+
+    def get_all_keys(self) -> list[dict[str, Any]]:
+        if not self._keys:
+            self._refresh_keys()
+        return list(self._keys.values())
+
+    def _refresh_keys(self) -> None:
+        if not self._jwks_uri:
+            self._discover()
+
+        try:
+            response = self._client.get(self._jwks_uri)  # type: ignore
+            response.raise_for_status()
+            jwks = response.json()
+
+            new_keys = {}
+            for key_data in jwks.get("keys", []):
+                kid = key_data.get("kid")
+                if kid:
+                    # Convert JWK to PEM/Public Key object using PyJWT helpers
+                    # Optimization: In real world, use
+                    # jwt.algorithms.RSAAlgorithm.from_jwk
+                    # Here we store raw JWK or converted object depending on what
+                    # validator expects. For PyJWT, passing the JWK dict or a key
+                    # object often works, but let's be explicit.
+                    # We will use PyJWT's internal helpers if available or just return
+                    # the dict as PyJWT decode() accepts a JWK dict set or specific key.
+                    # Ideally we convert distinct key per algorithm.
+
+                    # For simplicity in this phase, we'll store the JWK dict.
+                    # The Validator adapter will need to handle the conversion if
+                    # needed, OR we implement conversion here.
+                    # Best practice: KeyProvider returns ready-to-use keys.
+                    import jwt.algorithms
+                    from jwt.algorithms import Algorithm
+
+                    # Try to get algo from 'alg' field first (e.g. RS256)
+                    alg_name = key_data.get("alg")
+                    algo: Algorithm | None = None
+                    if alg_name:
+                        algo = jwt.algorithms.get_default_algorithms().get(alg_name)
+                    else:
+                        # Fallback for RSA if alg is missing but kty is RSA
+                        if key_data.get("kty") == "RSA":
+                            algo = jwt.algorithms.RSAAlgorithm  # type: ignore
+                        else:
+                            algo = None
+
+                    if algo:
+                        public_key = algo.from_jwk(key_data)
+                        new_keys[kid] = public_key
+
+            self._keys = new_keys
+
+        except Exception as e:
+            raise OpenShieldError(f"Failed to refresh JWKS: {e!s}") from e
+
+    def _discover(self) -> None:
+        try:
+            disco_url = f"{self.issuer_url}/.well-known/openid-configuration"
+            response = self._client.get(disco_url)
+            response.raise_for_status()
+            config = response.json()
+            self._jwks_uri = config.get("jwks_uri")
+            if not self._jwks_uri:
+                raise ConfigurationError(
+                    "Pre-discovery failed: jwks_uri not found in OIDC config"
+                )
+        except Exception as e:
+            raise ConfigurationError(
+                f"OIDC discovery failed for {self.issuer_url}: {e!s}"
+            ) from e

open_shield/adapters/token_validator.py

@@ -0,0 +1,75 @@
+from typing import Any
+
+import jwt
+from jwt.exceptions import ExpiredSignatureError
+from jwt.exceptions import InvalidTokenError as PyJWTError
+
+from open_shield.domain.entities import Token
+from open_shield.domain.exceptions import (
+    ExpiredTokenError,
+    InvalidSignatureError,
+    TokenValidationError,
+)
+from open_shield.domain.ports import TokenValidatorPort
+
+
+class PyJWTValidator(TokenValidatorPort):
+    """
+    Adapter that uses PyJWT to validate tokens.
+    """
+
+    def __init__(
+        self,
+        key_provider: Any | None = None,
+        algorithms: list[str] | None = None,
+        audience: str | None = None,
+        issuer: str | None = None,
+    ) -> None:
+        self.key_provider = key_provider
+        self.algorithms = algorithms or ["RS256"]
+        self.audience = audience
+        self.issuer = issuer
+
+    def validate_token(self, token_string: str) -> Token:
+        try:
+            # 1. Decode unverified header to get key ID (kid)
+            header = jwt.get_unverified_header(token_string)
+            kid = header.get("kid")
+
+            key = None
+            if self.key_provider and kid:
+                key = self.key_provider.get_key(kid)
+
+            # 2. Decode and validate
+            # options={"verify_signature": True} is default
+            payload = jwt.decode(
+                token_string,
+                key=key,  # type: ignore
+                algorithms=self.algorithms,
+                audience=self.audience,
+                issuer=self.issuer,
+                options={
+                    "verify_exp": True,
+                    "verify_aud": bool(self.audience),
+                    "verify_iss": bool(self.issuer),
+                },
+            )
+
+            return Token(raw=token_string, claims=payload)
+
+        except ExpiredSignatureError as e:
+            raise ExpiredTokenError(f"Token expired: {e!s}") from e
+        except PyJWTError as e:
+            # Map generic PyJWT errors to specific domain errors if possible
+            if "Signature verification failed" in str(e):
+                raise InvalidSignatureError(f"Invalid signature: {e!s}") from e
+            raise TokenValidationError(f"Token validation failed: {e!s}") from e
+        except Exception as e:
+            # Fallback for unexpected errors
+            raise TokenValidationError(f"Unexpected validation error: {e!s}") from e
+
+    def decode_unverified(self, token_string: str) -> dict[str, Any]:
+        try:
+            return jwt.decode(token_string, options={"verify_signature": False})
+        except PyJWTError as e:
+            raise TokenValidationError(f"Failed to decode token: {e!s}") from e

open_shield/api/__init__.py

@@ -0,0 +1,3 @@
+from . import fastapi
+
+__all__ = ["fastapi"]

open_shield/api/fastapi/__init__.py

@@ -0,0 +1,4 @@
+from .dependencies import RequireRole, RequireScope, get_user_context
+from .middleware import OpenShieldMiddleware
+
+__all__ = ["OpenShieldMiddleware", "RequireRole", "RequireScope", "get_user_context"]

open_shield/api/fastapi/dependencies.py

@@ -0,0 +1,47 @@
+from fastapi import Depends, HTTPException, Request
+
+from open_shield.domain.entities import UserContext
+from open_shield.domain.exceptions import AuthorizationError
+from open_shield.domain.services import AuthorizationService
+
+
+def get_user_context(request: Request) -> UserContext:
+    """
+    Dependency to retrieve the UserContext from request.state.
+    Assumes OpenShieldMiddleware has run.
+    """
+    if not hasattr(request.state, "user_context"):
+        raise HTTPException(status_code=401, detail="Authentication required")
+    from typing import cast
+
+    return cast(UserContext, request.state.user_context)
+
+
+class RequireScope:
+    """Dependency that enforces a required scope."""
+
+    def __init__(self, scope: str):
+        self.scope = scope
+        self.auth_service = AuthorizationService()
+
+    def __call__(self, context: UserContext = Depends(get_user_context)) -> UserContext:
+        try:
+            self.auth_service.require_scope(context, self.scope)
+        except AuthorizationError as e:
+            raise HTTPException(status_code=403, detail=str(e)) from e
+        return context
+
+
+class RequireRole:
+    """Dependency that enforces one of the required roles."""
+
+    def __init__(self, roles: list[str]):
+        self.roles = roles
+        self.auth_service = AuthorizationService()
+
+    def __call__(self, context: UserContext = Depends(get_user_context)) -> UserContext:
+        try:
+            self.auth_service.require_any_role(context, self.roles)
+        except AuthorizationError as e:
+            raise HTTPException(status_code=403, detail=str(e)) from e
+        return context

open_shield/api/fastapi/middleware.py

@@ -0,0 +1,85 @@
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.types import ASGIApp
+
+from open_shield.adapters import OIDCDiscoKeyProvider, OpenShieldConfig, PyJWTValidator
+from open_shield.domain.exceptions import OpenShieldError, TokenValidationError
+from open_shield.domain.services import TokenService
+
+
+class OpenShieldMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware that intercepts requests, validates the Authorization header,
+    and attaches the UserContext to the request state.
+
+    Attributes:
+        app: The ASGI application.
+        token_service: The domain service for validation.
+        config: The SDK configuration.
+        exclude_paths: A set of paths to exclude from authentication.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        config: OpenShieldConfig,
+        exclude_paths: set[str] | None = None,
+    ):
+        super().__init__(app)
+        self.config = config
+        self.exclude_paths = exclude_paths or {
+            "/docs",
+            "/openapi.json",
+            "/redoc",
+            "/health",
+        }
+
+        # Initialize dependencies
+        # In a real app, these might be injected, but middleware initialization is often
+        # the composition root.
+        key_provider = OIDCDiscoKeyProvider(issuer_url=config.ISSUER_URL)
+        validator = PyJWTValidator(
+            key_provider=key_provider,
+            algorithms=config.ALGORITHMS,
+            audience=config.AUDIENCE,
+            issuer=config.ISSUER_URL,
+        )
+        self.token_service = TokenService(validator=validator)
+
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        if request.url.path in self.exclude_paths:
+            return await call_next(request)
+
+        auth_header = request.headers.get("Authorization")
+        if not auth_header:
+            # Basic check, detailed handling usually done by dependency or explicit 401
+            # If we want global enforcement, strictly 401 here.
+            # Return 401.
+            return Response("Missing Authorization Header", status_code=401)
+
+        try:
+            scheme, token = auth_header.split()
+            if scheme.lower() != "bearer":
+                return Response("Invalid Authorization Scheme", status_code=401)
+
+            user_context = self.token_service.validate_and_extract(token)
+
+            # Attach to request.state for downstream access
+            request.state.user_context = user_context
+
+            # Enforce global require_scopes/roles if configured?
+            # Usually better handled in route dependencies.
+
+        except (ValueError, TokenValidationError) as e:
+            return Response(f"Unauthorized: {e!s}", status_code=401)
+        except OpenShieldError as e:
+            return Response(f"Forbidden: {e!s}", status_code=403)
+        except Exception:
+            # Log this error
+            return Response(
+                "Internal Server Error during Authentication", status_code=500
+            )
+
+        return await call_next(request)

open_shield/domain/__init__.py

@@ -0,0 +1,18 @@
+from .entities import TenantContext, Token, User, UserContext
+from .exceptions import (
+    AuthorizationError,
+    ConfigurationError,
+    OpenShieldError,
+    TokenValidationError,
+)
+
+__all__ = [
+    "AuthorizationError",
+    "ConfigurationError",
+    "OpenShieldError",
+    "TenantContext",
+    "Token",
+    "TokenValidationError",
+    "User",
+    "UserContext",
+]

open_shield/domain/entities.py

@@ -0,0 +1,59 @@
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Entity(BaseModel):
+    """Base class for all domain entities."""
+
+    model_config = ConfigDict(frozen=True)
+
+
+class TenantContext(Entity):
+    """Represents the tenant context extracted from a token."""
+
+    tenant_id: str = Field(..., description="Unique identifier for the tenant")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Additional tenant metadata"
+    )
+
+
+class User(Entity):
+    """Represents an authenticated user."""
+
+    id: str = Field(..., description="Unique user identifier (sub)")
+    email: str | None = Field(None, description="User email address")
+    roles: list[str] = Field(default_factory=list, description="Assigned roles")
+    scopes: list[str] = Field(
+        default_factory=list, description="Granted scopes/permissions"
+    )
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Additional user attributes"
+    )
+
+
+class Token(Entity):
+    """Represents a raw and parsed authentication token."""
+
+    raw: str = Field(..., description="The raw JWT string")
+    claims: dict[str, Any] = Field(..., description="The parsed claims dictionary")
+
+    @property
+    def issuer(self) -> str | None:
+        return self.claims.get("iss")
+
+    @property
+    def audience(self) -> str | list[str] | None:
+        return self.claims.get("aud")
+
+    @property
+    def subject(self) -> str | None:
+        return self.claims.get("sub")
+
+
+class UserContext(Entity):
+    """Aggregates User, Token, and Tenant information for a request."""
+
+    user: User
+    token: Token
+    tenant: TenantContext | None = None

open_shield/domain/exceptions.py

@@ -0,0 +1,40 @@
+class OpenShieldError(Exception):
+    """Base exception for all Open Shield errors."""
+
+    pass
+
+
+class ConfigurationError(OpenShieldError):
+    """Raised when the SDK configuration is invalid."""
+
+    pass
+
+
+class TokenValidationError(OpenShieldError):
+    """Base exception for token validation failures."""
+
+    pass
+
+
+class InvalidSignatureError(TokenValidationError):
+    """Raised when the token signature is invalid."""
+
+    pass
+
+
+class ExpiredTokenError(TokenValidationError):
+    """Raised when the token has expired."""
+
+    pass
+
+
+class InvalidClaimsError(TokenValidationError):
+    """Raised when token claims (iss, aud, etc.) are invalid."""
+
+    pass
+
+
+class AuthorizationError(OpenShieldError):
+    """Raised when a user lacks required permissions."""
+
+    pass

open_shield/domain/ports/__init__.py

@@ -0,0 +1,4 @@
+from .key_provider import KeyProviderPort
+from .token_validator import TokenValidatorPort
+
+__all__ = ["KeyProviderPort", "TokenValidatorPort"]

open_shield/domain/ports/key_provider.py

@@ -0,0 +1,32 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class KeyProviderPort(ABC):
+    """Abstract interface for retrieving and caching JSON Web Keys (JWKS)."""
+
+    @abstractmethod
+    def get_key(self, kid: str) -> Any:
+        """
+        Retrieve a specific key by Key ID (kid).
+
+        Args:
+            kid: The Key ID to search for.
+
+        Returns:
+            The key object (implementation dependent, usually a public key).
+
+        Raises:
+            KeyCorrectionError: If the key cannot be found or retrieved.
+        """
+        pass
+
+    @abstractmethod
+    def get_all_keys(self) -> list[dict[str, Any]]:
+        """
+        Retrieve all available keys in JWK format.
+
+        Returns:
+            A list of JWK dictionaries.
+        """
+        pass

open_shield/domain/ports/token_validator.py

@@ -0,0 +1,38 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+from open_shield.domain.entities import Token
+
+
+class TokenValidatorPort(ABC):
+    """Abstract interface for validating JWT tokens."""
+
+    @abstractmethod
+    def validate_token(self, token_string: str) -> Token:
+        """
+        Parse and validate a raw JWT string.
+
+        Args:
+            token_string: The raw JWT string.
+
+        Returns:
+            A validated Token entity.
+
+        Raises:
+            TokenValidationError: If validation fails (expired, invalid signature, etc).
+        """
+        pass
+
+    @abstractmethod
+    def decode_unverified(self, token_string: str) -> dict[str, Any]:
+        """
+        Decode the token without verification (useful for inspecting headers/claims
+        pre-validation).
+
+        Args:
+            token_string: The raw JWT string.
+
+        Returns:
+            The decoded claims dictionary.
+        """
+        pass

open_shield/domain/services/__init__.py

@@ -0,0 +1,4 @@
+from .authorization_service import AuthorizationService
+from .token_service import TokenService
+
+__all__ = ["AuthorizationService", "TokenService"]

open_shield/domain/services/authorization_service.py

@@ -0,0 +1,45 @@
+from open_shield.domain.entities import UserContext
+from open_shield.domain.exceptions import AuthorizationError
+
+
+class AuthorizationService:
+    """
+    Domain service for enforcing access control policies on a UserContext.
+    """
+
+    def require_scope(self, context: UserContext, required_scope: str) -> None:
+        """
+        Ensure the user has the required scope.
+
+        Args:
+            context: The authenticated user context.
+            required_scope: The specific scope string required.
+
+        Raises:
+            AuthorizationError: If the scope is missing.
+        """
+        if required_scope not in context.user.scopes:
+            # Check for exact match first.
+            # TODO: Implement hierarchical scope checking (e.g. read:users implies
+            # read:users:self) if needed.
+            raise AuthorizationError(f"Missing required scope: {required_scope}")
+
+    def require_any_role(self, context: UserContext, roles: list[str]) -> None:
+        """
+        Ensure the user has at least one of the required roles.
+
+        Args:
+            context: The authenticated user context.
+            roles: A list of allowed roles.
+
+        Raises:
+            AuthorizationError: If the user has none of the required roles.
+        """
+        user_roles = set(context.user.roles)
+        required_roles = set(roles)
+
+        if not user_roles.intersection(required_roles):
+            raise AuthorizationError(
+                f"Missing required role. User has: {user_roles}. "
+                f"Required one of: {required_roles}"
+            )

open_shield/domain/services/token_service.py

@@ -0,0 +1,83 @@
+from open_shield.domain.entities import TenantContext, Token, User, UserContext
+from open_shield.domain.exceptions import TokenValidationError
+from open_shield.domain.ports import TokenValidatorPort
+
+
+class TokenService:
+    """
+    Domain service for orchestrating token validation and context extraction.
+    Dependencies are injected via constructor (DIP).
+    """
+
+    def __init__(self, validator: TokenValidatorPort):
+        self.validator = validator
+
+    def validate_and_extract(self, token_string: str) -> UserContext:
+        """
+        Validate a raw token string and extract the user context.
+
+        Args:
+            token_string: The raw JWT from the Authorization header.
+
+        Returns:
+            A populated UserContext object.
+
+        Raises:
+            TokenValidationError: If validation fails.
+        """
+        token = self.validator.validate_token(token_string)
+        user = self._extract_user(token)
+        tenant = self._extract_tenant(token)
+
+        return UserContext(user=user, token=token, tenant=tenant)
+
+    def _extract_user(self, token: Token) -> User:
+        """Extract user identity and permissions from the token."""
+        # Default claim mapping (stateless)
+        # TODO: Make claim mapping configurable
+        sub = token.subject
+        if not sub:
+            raise TokenValidationError("Token missing 'sub' claim")
+
+        email = token.claims.get("email")
+        # Standard claim for roles in Keycloak/Auth0 varies.
+        # We look for 'roles', 'realm_access.roles', or 'permissions'.
+        roles = token.claims.get("roles", [])
+        if "realm_access" in token.claims and isinstance(
+            token.claims["realm_access"], dict
+        ):
+            roles.extend(token.claims["realm_access"].get("roles", []))
+
+        scopes = (
+            token.claims.get("scope", "").split()
+            if isinstance(token.claims.get("scope"), str)
+            else []
+        )
+
+        return User(
+            id=sub,
+            email=email,
+            roles=list(set(roles)),  # Deduplicate
+            scopes=scopes,
+            metadata=token.claims,
+        )
+
+    def _extract_tenant(self, token: Token) -> TenantContext | None:
+        """
+        Extract tenant context from the token.
+        Strategies:
+        1. Custom claim 'tid' or 'org_id'
+        2. Issuer URL parsing (e.g. https://auth.com/realms/{tenant})
+        """
+        # Simple default strategy: look for specific claims
+        # TODO: Make tenant extraction strategy configurable
+        tid = (
+            token.claims.get("tid")
+            or token.claims.get("org_id")
+            or token.claims.get("tenant_id")
+        )
+
+        if tid:
+            return TenantContext(tenant_id=tid, metadata={})
+
+        return None

open_shield_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: open-shield-python
+Version: 0.1.0
+Summary: Vendor-agnostic authentication and authorization enforcement SDK
+Project-URL: Repository, https://github.com/prayog-ai-labs/open-shield-python
+Project-URL: Issues, https://github.com/prayog-ai-labs/open-shield-python/issues
+Author-email: Avinash <avinash@prayog.ai>
+License: MIT
+License-File: LICENSE
+Keywords: authentication,authorization,fastapi,jwt,oidc,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: fastapi>=0.129.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyjwt>=2.8.0
+Description-Content-Type: text/markdown
+
+# Open Shield Python SDK
+
+Vendor-agnostic authentication and authorization enforcement SDK for Python.
+
+Open Shield allows you to enforce authentication (AuthN) and authorization (AuthZ) in your Python applications without tightly coupling your code to a specific identity provider (like Auth0, Keycloak, or Cognito).
+
+## Features
+
+- **Vendor Neutral**: Works with any OIDC-compliant provider.
+- **Framework Agnostic**: Core logic is pure Python; first-class support for **FastAPI**.
+- **Clean Architecture**: Domain logic is isolated from infrastructure concerns.
+- **Type Safe**: Fully typed and checked with `mypy`.
+- **Automatic JWKS Rotation**: Fetches and caches keys from your provider's OIDC discovery endpoint.
+
+## Installation
+
+```bash
+pip install open-shield-python
+```
+
+## Quick Start (FastAPI)
+
+1. **Configure Environment**
+
+Set the following environment variables:
+
+```bash
+OPEN_SHIELD_ISSUER_URL=https://your-auth-domain.com/realms/myrealm
+OPEN_SHIELD_AUDIENCE=my-api-identifier
+```
+
+2. **Add Middleware**
+
+```python
+from fastapi import FastAPI, Depends
+from open_shield.api.fastapi import OpenShieldMiddleware, get_user_context, RequireScope, RequireRole
+from open_shield.adapters import OpenShieldConfig
+from open_shield.domain.entities import UserContext
+
+app = FastAPI()
+
+# Load config from environment
+config = OpenShieldConfig()
+
+# Add global authentication middleware
+app.add_middleware(OpenShieldMiddleware, config=config)
+
+# Public route (excluded by default: /docs, /openapi.json, /redoc, /health)
+@app.get("/health")
+def health():
+    return {"status": "ok"}
+
+# Protected route (Authentication required)
+@app.get("/users/me")
+def read_current_user(context: UserContext = Depends(get_user_context)):
+    return {
+        "id": context.user.id,
+        "email": context.user.email,
+        "roles": context.user.roles
+    }
+
+# Scoped route (Authorization required)
+@app.get("/admin/dashboard")
+def admin_dashboard(context: UserContext = Depends(RequireScope("read:admin"))):
+    return {"data": "secret admin data"}
+
+# Role-based route
+@app.get("/manager/reports")
+def reports(context: UserContext = Depends(RequireRole(["manager", "admin"]))):
+    return {"reports": []}
+```
+
+## Architecture
+
+This SDK follows **Clean Architecture** principles:
+
+- **Domain Layer**: Pure Python logic, entities, and interfaces (Ports). Zero external dependencies.
+- **Adapters Layer**: Concrete implementations of Ports (e.g., `PyJWT` for validation, `httpx` for JWKS).
+- **API Layer**: Framework specific glue code (e.g., FastAPI Middleware).
+
+## configuration
+
+| Environment Variable | Description | Default |
+|----------------------|-------------|---------|
+| `OPEN_SHIELD_ISSUER_URL` | OIDC Issuer URL (required) | - |
+| `OPEN_SHIELD_AUDIENCE` | Expected audience (`aud` claim) | None |
+| `OPEN_SHIELD_ALGORITHMS` | Allowed signing algorithms | `["RS256"]` |
+| `OPEN_SHIELD_REQUIRE_SCOPES` | Enforce scope presence | `True` |
+
+## Development
+
+This project uses `uv` for dependency management.
+
+```bash
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Lint and Format
+uv run ruff check .
+```

open_shield_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+open_shield/adapters/__init__.py,sha256=8FC2rMABRPcXZkl_d5DlFeknMYE5uYCe78mB-LsKLYE,202
+open_shield/adapters/config.py,sha256=qx4XTFxMrtan1OLEmsZU1Os5-zKBs83G8KHI3DZDCKI,634
+open_shield/adapters/key_provider.py,sha256=9zB3PyZZ_3t8wgzUxVWeXHv73Ktc9aI4PnmtAxVGFXc,4271
+open_shield/adapters/token_validator.py,sha256=yXtnMiABrtsKEXMBDoNrNOrrx2Tpajqz7nCx1PV3Ipw,2653
+open_shield/api/__init__.py,sha256=nWkMRvKxlDGQ3rvy6sBTePl8wxCQAAYzoFLhswk-J4Y,45
+open_shield/api/fastapi/__init__.py,sha256=Z2ZLoj_sUY_ZWDx3hCZGvg3YN-BaK2c7yS6HvY_Jh6Q,202
+open_shield/api/fastapi/dependencies.py,sha256=cal5CprB9ASnCjnFAwmU5qH7NwxXPuSHnKljYvRf2sc,1622
+open_shield/api/fastapi/middleware.py,sha256=iEdtB4krvuMJm3zwj3bxQiAgNWaZ1WgnYvBO2K8CtCM,3144
+open_shield/domain/__init__.py,sha256=Oca7GxVhjz5klLy5qTXogPT1jBSSqRtyYO6LN9qokk4,368
+open_shield/domain/entities.py,sha256=5VDt5iJ3PQmQYrj-npEPM39sUfglF0H5dVhlfzcYwK8,1676
+open_shield/domain/exceptions.py,sha256=ECizwHbgKNJeSdP0tTotDoDXth3gWnIoQjzdGjq8pkI,779
+open_shield/domain/ports/__init__.py,sha256=Uv_NXCSY2QY18M875r6DBX5ibmw6ea19I-6S091N0Dc,143
+open_shield/domain/ports/key_provider.py,sha256=sKb5ePgDPbphMcAuNVpCD1jCgu3KGk07ZHNjbq7g2qs,776
+open_shield/domain/ports/token_validator.py,sha256=y9LnLoaMhiOWDwnURmJ4PKAypzr--tq1YjWnar-wfiA,938
+open_shield/domain/services/__init__.py,sha256=H65tB4iEDNyKT2e34GkqCovzREK7yJXAKrQqS-lv4ZM,148
+open_shield/domain/services/authorization_service.py,sha256=YtMpLhzCUFxoQpxn_e28qZ9MVcaBaGGsqccK67Hd4tw,1581
+open_shield/domain/services/token_service.py,sha256=aNu5PNZJzTJ4Z0SPtMAD5isYecYn4m7qCMzG72j0ts0,2778
+open_shield_python-0.1.0.dist-info/METADATA,sha256=aNt-xkCA4FBJatYOHKKqtVu6q4raOdO_YItx0ct8vNY,4200
+open_shield_python-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+open_shield_python-0.1.0.dist-info/licenses/LICENSE,sha256=33ACXoHh8AAfHNbU6jphGhoIHyJOccH1mVG1lXn60DQ,1071
+open_shield_python-0.1.0.dist-info/RECORD,,

open_shield_python-0.1.0.dist-info/WHEEL

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

open_shield_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prayog AI Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.