open-shield-python 0.1.0__tar.gz → 0.2.1__tar.gz

{open_shield_python-0.1.0 → open_shield_python-0.2.1}/CONTRIBUTING.md

@@ -27,18 +27,11 @@ Thank you for your interest in contributing to Open Shield! We welcome contribut
 
 ## Code Standards
 
-- **Linting & Testing**: We provide a convenience script.
-  - Run `./scripts/verify.sh` to execute `ruff format`, `ruff check`, `mypy`, and `pytest` in one go.
-  - **Always** run this script before pushing your changes.
+- **Linting**: We use `ruff`. Run `uv run ruff check .` before committing.
+- **Typing**: We use `mypy`. Run `uv run mypy .` to ensure type safety.
+- **Architecture**: Please respect the Clean Architecture layers (`domain`, `adapters`, `api`).
 - **Commits**: Follow [Conventional Commits](https://www.conventionalcommits.org/).
 
-## Assistant / Agent Workflow
-
-If you are an AI assistant working on this repository:
-1. **Always** check for existing workflows in `.agent/workflows`.
-2. **Prioritize** using `/safe-commit` when finalizing a task to ensure quality gates are met.
-3. **Read** `.agent/rules.md` for project-specific behavioral rules.
-
 ## Pull Requests
 
 1. Fork the repo and create your branch (`feat/amazing-feature`).

{open_shield_python-0.1.0 → open_shield_python-0.2.1}/PKG-INFO

@@ -1,21 +1,8 @@
 Metadata-Version: 2.4
 Name: open-shield-python
-Version: 0.1.0
+Version: 0.2.1
 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
@@ -27,6 +14,8 @@ Description-Content-Type: text/markdown
 
 # Open Shield Python SDK
 
+[![CI](https://github.com/prayog-ai-labs/open-shield-python/actions/workflows/ci.yml/badge.svg)](https://github.com/prayog-ai-labs/open-shield-python/actions/workflows/ci.yml)
+
 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).

{open_shield_python-0.1.0 → open_shield_python-0.2.1}/README.md

@@ -1,5 +1,7 @@
 # Open Shield Python SDK
 
+[![CI](https://github.com/prayog-ai-labs/open-shield-python/actions/workflows/ci.yml/badge.svg)](https://github.com/prayog-ai-labs/open-shield-python/actions/workflows/ci.yml)
+
 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).

{open_shield_python-0.1.0 → open_shield_python-0.2.1}/docs/planning/tasks.md

@@ -19,13 +19,7 @@
     - [x] Create FastAPI Middleware (depends on `TokenService`) <!-- id: 16 -->
     - [x] Implement FastAPI Dependencies (`DependencyInjection`) <!-- id: 17 -->
     - [x] Map Domain Exceptions to HTTP Responses <!-- id: 18 -->
-- [/] Phase 4: Integration Testing & Verification <!-- id: 19 -->
-    - [x] **Research Logto Integration** <!-- id: 23 -->
-    - [x] **Create Logto Integration Plan** <!-- id: 25 -->
-    - [x] **Implement Logto Integration Tests** <!-- id: 26 -->
-        - [x] Create `docker-compose.test.yml` with Logto <!-- id: 27 -->
-        - [x] Create setup scripts/fixtures for Logto <!-- id: 28 -->
-        - [x] Develop Integration Test Suite (`tests/integration/auth_flow`) <!-- id: 29 -->
-    - [ ] Comprehensive Testing (Unit/Integration) <!-- id: 21 -->
-    - [ ] Documentation (Usage, Architecture) <!-- id: 20 -->
-    - [ ] Publish to PyPI <!-- id: 22 -->
+- [x] Phase 4: Polish & Release <!-- id: 19 -->
+    - [x] Comprehensive Testing (Unit/Integration) <!-- id: 21 -->
+    - [x] Documentation (Usage, Architecture) <!-- id: 20 -->
+    - [x] Publish to PyPI <!-- id: 22 -->

{open_shield_python-0.1.0 → open_shield_python-0.2.1}/pyproject.toml

@@ -1,25 +1,9 @@
 [project]
 name = "open-shield-python"
-version = "0.1.0"
+version = "0.2.1"
 description = "Vendor-agnostic authentication and authorization enforcement SDK"
 readme = "README.md"
 requires-python = ">=3.12"
-authors = [
-  { name = "Avinash", email = "avinash@prayog.ai" },
-]
-license = { text = "MIT" }
-classifiers = [
-    "Development Status :: 4 - Beta",
-    "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.12",
-    "Operating System :: OS Independent",
-    "Topic :: Security",
-    "Topic :: Software Development :: Libraries :: Python Modules",
-]
-keywords = ["authentication", "authorization", "oidc", "jwt", "security", "fastapi"]
-
 dependencies = [
     "pydantic>=2.0.0",
     "pydantic-settings>=2.0.0",
@@ -29,10 +13,6 @@ dependencies = [
     "fastapi>=0.129.0",
 ]
 
-[project.urls]
-Repository = "https://github.com/prayog-ai-labs/open-shield-python"
-Issues = "https://github.com/prayog-ai-labs/open-shield-python/issues"
-
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
@@ -71,5 +51,4 @@ dev = [
     "respx>=0.22.0",
     "ruff>=0.15.0",
     "uvicorn>=0.40.0",
-    "pytest-asyncio>=0.23.0",
 ]

open_shield_python-0.2.1/src/open_shield/adapters/config.py

@@ -0,0 +1,49 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class OpenShieldConfig(BaseSettings):
+    """Configuration for Open Shield SDK.
+
+    Loads settings from environment variables (OPEN_SHIELD_ prefix).
+
+    OIDC Settings:
+        ISSUER_URL: OIDC provider's issuer URL (required).
+        AUDIENCE: Expected audience claim value.
+        ALGORITHMS: Allowed JWT signing algorithms.
+
+    Claim Mapping:
+        USER_ID_CLAIM: Claim containing the unique user identifier.
+        EMAIL_CLAIM: Claim containing the user's email address.
+        TENANT_ID_CLAIM: Claim containing tenant/organization ID.
+        SCOPE_CLAIM: Claim containing space-separated scopes.
+        ROLES_CLAIM: Claim containing user roles.
+        TENANT_FALLBACK: Strategy when tenant claim is missing ("sub" | "none").
+
+    Authorization:
+        REQUIRE_SCOPES: Whether to enforce scope presence globally.
+        REQUIRE_ROLES: Whether to enforce role presence globally.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="OPEN_SHIELD_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # OIDC
+    ISSUER_URL: str
+    AUDIENCE: str | None = None
+    ALGORITHMS: list[str] = ["RS256"]
+
+    # Claim mapping (identity-provider agnostic)
+    USER_ID_CLAIM: str = "sub"
+    EMAIL_CLAIM: str = "email"
+    TENANT_ID_CLAIM: str = "tid"
+    SCOPE_CLAIM: str = "scope"
+    ROLES_CLAIM: str = "roles"
+    TENANT_FALLBACK: str = "none"
+
+    # Authorization defaults
+    REQUIRE_SCOPES: bool = True
+    REQUIRE_ROLES: bool = False

open_shield_python-0.2.1/src/open_shield/api/fastapi/__init__.py

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

{open_shield_python-0.1.0 → open_shield_python-0.2.1}/src/open_shield/api/fastapi/dependencies.py

@@ -1,3 +1,5 @@
+from typing import cast
+
 from fastapi import Depends, HTTPException, Request
 
 from open_shield.domain.entities import UserContext
@@ -6,13 +8,27 @@ 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.
+    """Dependency to retrieve the UserContext from request.state.
+
+    Assumes OpenShieldMiddleware has run and attached user_context.
+
+    Raises:
+        HTTPException: 401 if no user context is found.
     """
     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)
+
+
+def get_optional_user_context(request: Request) -> UserContext | None:
+    """Dependency for optional authentication.
+
+    Returns None instead of 401 when no credentials are provided.
+    Useful for routes that support both authenticated and anonymous access.
+    """
+    if not hasattr(request.state, "user_context"):
+        return None
 
     return cast(UserContext, request.state.user_context)
 

{open_shield_python-0.1.0 → open_shield_python-0.2.1}/src/open_shield/api/fastapi/middleware.py

@@ -5,13 +5,16 @@ 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
+from open_shield.domain.services.claim_mapping import ClaimMapping
 
 
 class OpenShieldMiddleware(BaseHTTPMiddleware):
-    """
-    Middleware that intercepts requests, validates the Authorization header,
+    """Middleware that intercepts requests, validates the Authorization header,
     and attaches the UserContext to the request state.
 
+    Supports configurable claim mapping via OpenShieldConfig, making it
+    compatible with any OIDC-compliant provider (Logto, Keycloak, Auth0, etc.).
+
     Attributes:
         app: The ASGI application.
         token_service: The domain service for validation.
@@ -34,9 +37,17 @@ class OpenShieldMiddleware(BaseHTTPMiddleware):
             "/health",
         }
 
-        # Initialize dependencies
-        # In a real app, these might be injected, but middleware initialization is often
-        # the composition root.
+        # Build claim mapping from config
+        claim_mapping = ClaimMapping(
+            user_id_claim=config.USER_ID_CLAIM,
+            email_claim=config.EMAIL_CLAIM,
+            tenant_id_claim=config.TENANT_ID_CLAIM,
+            scope_claim=config.SCOPE_CLAIM,
+            roles_claim=config.ROLES_CLAIM,
+            tenant_fallback=config.TENANT_FALLBACK,
+        )
+
+        # Initialize dependencies (composition root)
         key_provider = OIDCDiscoKeyProvider(issuer_url=config.ISSUER_URL)
         validator = PyJWTValidator(
             key_provider=key_provider,
@@ -44,7 +55,10 @@ class OpenShieldMiddleware(BaseHTTPMiddleware):
             audience=config.AUDIENCE,
             issuer=config.ISSUER_URL,
         )
-        self.token_service = TokenService(validator=validator)
+        self.token_service = TokenService(
+            validator=validator,
+            claim_mapping=claim_mapping,
+        )
 
     async def dispatch(
         self, request: Request, call_next: RequestResponseEndpoint
@@ -54,9 +68,6 @@ class OpenShieldMiddleware(BaseHTTPMiddleware):
 
         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:
@@ -69,15 +80,11 @@ class OpenShieldMiddleware(BaseHTTPMiddleware):
             # 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
             )

{open_shield_python-0.1.0 → open_shield_python-0.2.1}/src/open_shield/domain/entities.py

@@ -27,6 +27,10 @@ class User(Entity):
     scopes: list[str] = Field(
         default_factory=list, description="Granted scopes/permissions"
     )
+    actor_type: str = Field(
+        default="user",
+        description="Inferred actor type: 'user', 'agent', or 'service'",
+    )
     metadata: dict[str, Any] = Field(
         default_factory=dict, description="Additional user attributes"
     )

open_shield_python-0.2.1/src/open_shield/domain/ports/__init__.py

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

open_shield_python-0.2.1/src/open_shield/domain/ports/tenant_resolver.py

@@ -0,0 +1,37 @@
+"""Port for resolving tenant context from machine client credentials.
+
+This port supports Case 3 (M2M clients) in the tenant resolution cascade:
+
+    1. M2M client → lookup_client_tenant(client_id) → tenant_id
+    2. Organization claim → organization_id → tenant_id
+    3. Fallback → sub → tenant_id (individual user mode only)
+
+Consumers implement this port to map client_id → tenant_id using their
+own registry (database, config file, Logto Management API, etc.).
+"""
+
+from abc import ABC, abstractmethod
+
+
+class TenantResolverPort(ABC):
+    """Resolves tenant context for machine-to-machine (M2M) clients.
+
+    M2M tokens (client_credentials flow) don't carry organization claims.
+    This port allows consumers to map a ``client_id`` to a ``tenant_id``
+    using their own backend registry.
+
+    If no resolver is provided to ``TokenService``, M2M tokens fall through
+    to the organization claim or sub fallback.
+    """
+
+    @abstractmethod
+    def resolve_tenant(self, client_id: str) -> str | None:
+        """Look up the tenant for a machine client.
+
+        Args:
+            client_id: The OAuth2 client_id from the token.
+
+        Returns:
+            The tenant_id if found, or None to continue the cascade.
+        """
+        ...

open_shield_python-0.2.1/src/open_shield/domain/services/__init__.py

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

open_shield_python-0.2.1/src/open_shield/domain/services/claim_mapping.py

@@ -0,0 +1,44 @@
+"""Configurable JWT claim-to-field mapping.
+
+Allows consumers to map any OIDC provider's claim names to Open Shield's
+internal user/tenant model without modifying SDK code.
+
+Examples:
+    # Logto
+    ClaimMapping(tenant_id_claim="organization_id")
+
+    # Keycloak
+    ClaimMapping(roles_claim="realm_access.roles", tenant_id_claim="tenant")
+
+    # Auth0
+    ClaimMapping(tenant_id_claim="https://myapp.com/org_id")
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ClaimMapping:
+    """Maps JWT claim names to semantic identity fields.
+
+    All fields have sensible defaults that work with most OIDC providers.
+    Override individual fields to match your provider's token format.
+
+    Attributes:
+        user_id_claim: Claim containing the unique user identifier.
+        email_claim: Claim containing the user's email address.
+        tenant_id_claim: Claim containing the tenant/organization ID.
+        scope_claim: Claim containing space-separated scopes.
+        roles_claim: Claim containing the user's roles.
+        tenant_fallback: Strategy when tenant claim is missing.
+            "sub" = fall back to user_id, "none" = no tenant.
+    """
+
+    user_id_claim: str = "sub"
+    email_claim: str = "email"
+    tenant_id_claim: str = "tid"
+    scope_claim: str = "scope"
+    roles_claim: str = "roles"
+    tenant_fallback: str = "none"

open_shield_python-0.2.1/src/open_shield/domain/services/token_service.py

@@ -0,0 +1,151 @@
+from open_shield.domain.entities import TenantContext, Token, User, UserContext
+from open_shield.domain.exceptions import TokenValidationError
+from open_shield.domain.ports import TenantResolverPort, TokenValidatorPort
+from open_shield.domain.services.claim_mapping import ClaimMapping
+
+
+class TokenService:
+    """Domain service for orchestrating token validation and context extraction.
+
+    Implements a 3-step tenant resolution cascade:
+        1. M2M client → lookup via TenantResolverPort (if provided)
+        2. Organization claim → configurable tenant_id_claim
+        3. Fallback → sub (if tenant_fallback="sub")
+
+    Args:
+        validator: Port for JWT validation.
+        claim_mapping: Configurable claim-to-field mapping.
+        tenant_resolver: Optional port for M2M client→tenant lookup.
+            If not provided, M2M tokens fall through to the org claim.
+    """
+
+    def __init__(
+        self,
+        validator: TokenValidatorPort,
+        claim_mapping: ClaimMapping | None = None,
+        tenant_resolver: TenantResolverPort | None = None,
+    ):
+        self.validator = validator
+        self.claims = claim_mapping or ClaimMapping()
+        self.tenant_resolver = tenant_resolver
+
+    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.
+
+        Uses the configured claim mapping to read fields from any
+        OIDC-compliant provider's token format.
+        """
+        sub = token.subject
+        if not sub:
+            raise TokenValidationError("Token missing 'sub' claim")
+
+        email = token.claims.get(self.claims.email_claim)
+
+        # Roles: support flat list and nested Keycloak-style realm_access
+        roles = token.claims.get(self.claims.roles_claim, [])
+        if isinstance(roles, str):
+            roles = [roles]
+        if "realm_access" in token.claims and isinstance(
+            token.claims["realm_access"], dict
+        ):
+            roles = list(roles)  # ensure mutable
+            roles.extend(token.claims["realm_access"].get("roles", []))
+
+        # Scopes: space-separated string or list
+        raw_scope = token.claims.get(self.claims.scope_claim, "")
+        scopes = raw_scope.split() if isinstance(raw_scope, str) else list(raw_scope)
+
+        # Actor type inference
+        actor_type = self._infer_actor_type(token.claims, roles)
+
+        return User(
+            id=sub,
+            email=email,
+            roles=list(set(roles)),  # Deduplicate
+            scopes=scopes,
+            actor_type=actor_type,
+            metadata=token.claims,
+        )
+
+    def _extract_tenant(self, token: Token) -> TenantContext | None:
+        """Extract tenant context using a 3-step cascade.
+
+        Resolution order:
+            1. M2M client lookup — If this is a client_credentials token
+               (sub == client_id) AND a TenantResolverPort is configured,
+               resolve tenant from the client registry.
+            2. Organization claim — Read the configured tenant_id_claim
+               (e.g. organization_id, tid, org_id).
+            3. Sub fallback — If tenant_fallback="sub", use the user's
+               subject as tenant_id (individual user mode).
+
+        Returns:
+            TenantContext if resolved, None if no tenant could be determined.
+        """
+        claims = token.claims
+        sub = token.subject
+
+        # --- Step 1: M2M client → tenant lookup ---
+        client_id = claims.get("client_id", claims.get("azp"))
+        is_m2m = client_id and sub and sub == client_id
+
+        if is_m2m and self.tenant_resolver:
+            resolved = self.tenant_resolver.resolve_tenant(client_id)
+            if resolved:
+                return TenantContext(
+                    tenant_id=resolved,
+                    metadata={"resolution": "m2m_lookup", "client_id": client_id},
+                )
+
+        # --- Step 2: Organization claim ---
+        tid = claims.get(self.claims.tenant_id_claim)
+        if tid:
+            return TenantContext(
+                tenant_id=tid,
+                metadata={"resolution": "claim", "claim": self.claims.tenant_id_claim},
+            )
+
+        # --- Step 3: Sub fallback (individual user mode) ---
+        if self.claims.tenant_fallback == "sub" and sub:
+            return TenantContext(
+                tenant_id=sub,
+                metadata={"resolution": "sub_fallback"},
+            )
+
+        return None
+
+    def _infer_actor_type(self, claims: dict, roles: list) -> str:  # type: ignore[type-arg]
+        """Infer actor type from token claims.
+
+        Heuristic:
+        - If 'client_id' == 'sub' (client credentials flow) → "service" or "agent"
+        - Default → "user"
+        """
+        sub = claims.get("sub", "")
+        client_id = claims.get("client_id", claims.get("azp", ""))
+
+        # Client credentials flow: sub == client_id (no human user)
+        if client_id and sub == client_id:
+            if "agent" in roles:
+                return "agent"
+            return "service"
+
+        return "user"