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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: open-shield-python
-Version: 0.2.0
+Version: 0.2.1
 Summary: Vendor-agnostic authentication and authorization enforcement SDK
 License-File: LICENSE
 Requires-Python: >=3.12

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

@@ -1,6 +1,6 @@
 [project]
 name = "open-shield-python"
-version = "0.2.0"
+version = "0.2.1"
 description = "Vendor-agnostic authentication and authorization enforcement SDK"
 readme = "README.md"
 requires-python = ">=3.12"

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.0 → open_shield_python-0.2.1}/src/open_shield/domain/services/token_service.py

@@ -1,27 +1,33 @@
 from open_shield.domain.entities import TenantContext, Token, User, UserContext
 from open_shield.domain.exceptions import TokenValidationError
-from open_shield.domain.ports import TokenValidatorPort
+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.
 
-    Dependencies are injected via constructor (DIP).
+    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.
-            Defaults to standard OIDC claim names if not provided.
+        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.
@@ -80,18 +86,49 @@ class TokenService:
         )
 
     def _extract_tenant(self, token: Token) -> TenantContext | None:
-        """Extract tenant context from the token.
+        """Extract tenant context using a 3-step cascade.
 
-        Uses the configured tenant_id_claim. Falls back to the
-        configured tenant_fallback strategy if the claim is missing.
+        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.
         """
-        tid = token.claims.get(self.claims.tenant_id_claim)
+        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 not tid and self.claims.tenant_fallback == "sub":
-            tid = token.subject
+        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={})
+            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
 

{open_shield_python-0.2.0 → open_shield_python-0.2.1}/tests/unit/domain/test_claim_mapping.py

@@ -1,7 +1,7 @@
 from typing import Any
 
 from open_shield.domain.entities import Token
-from open_shield.domain.ports import TokenValidatorPort
+from open_shield.domain.ports import TenantResolverPort, TokenValidatorPort
 from open_shield.domain.services import TokenService
 from open_shield.domain.services.claim_mapping import ClaimMapping
 
@@ -152,3 +152,96 @@ def test_actor_type_azp_fallback() -> None:
 
     ctx = service.validate_and_extract("token")
     assert ctx.user.actor_type == "service"
+
+
+# ---------------------------------------------------------------------------
+# Tenant Resolution Cascade Tests
+# ---------------------------------------------------------------------------
+
+
+class _MockTenantResolver(TenantResolverPort):
+    """Mock tenant resolver for testing M2M lookup."""
+
+    def __init__(self, mapping: dict[str, str]) -> None:
+        self._mapping = mapping
+
+    def resolve_tenant(self, client_id: str) -> str | None:
+        return self._mapping.get(client_id)
+
+
+def test_cascade_step1_m2m_resolver() -> None:
+    """Step 1: M2M token with resolver → tenant from registry."""
+    claims = {"sub": "client_abc", "client_id": "client_abc"}
+    resolver = _MockTenantResolver({"client_abc": "tenant_from_registry"})
+    service = TokenService(
+        _MockValidator(claims),
+        tenant_resolver=resolver,
+    )
+
+    ctx = service.validate_and_extract("token")
+    assert ctx.tenant is not None
+    assert ctx.tenant.tenant_id == "tenant_from_registry"
+    assert ctx.tenant.metadata["resolution"] == "m2m_lookup"
+
+
+def test_cascade_step1_m2m_no_resolver_falls_through() -> None:
+    """Step 1 skipped: M2M token but no resolver → falls to step 2/3."""
+    claims = {"sub": "client_abc", "client_id": "client_abc", "tid": "org_123"}
+    service = TokenService(
+        _MockValidator(claims),
+        # No tenant_resolver provided
+    )
+
+    ctx = service.validate_and_extract("token")
+    assert ctx.tenant is not None
+    assert ctx.tenant.tenant_id == "org_123"
+    assert ctx.tenant.metadata["resolution"] == "claim"
+
+
+def test_cascade_step1_resolver_returns_none_falls_through() -> None:
+    """Step 1: Resolver doesn't know this client → falls to step 2."""
+    claims = {
+        "sub": "unknown_client",
+        "client_id": "unknown_client",
+        "organization_id": "fallback_org",
+    }
+    resolver = _MockTenantResolver({})  # Empty — won't match
+    cm = ClaimMapping(tenant_id_claim="organization_id")
+    service = TokenService(
+        _MockValidator(claims),
+        claim_mapping=cm,
+        tenant_resolver=resolver,
+    )
+
+    ctx = service.validate_and_extract("token")
+    assert ctx.tenant is not None
+    assert ctx.tenant.tenant_id == "fallback_org"
+    assert ctx.tenant.metadata["resolution"] == "claim"
+
+
+def test_cascade_step2_org_claim_priority() -> None:
+    """Step 2: Organization claim takes priority over sub fallback."""
+    claims = {"sub": "user_123", "organization_id": "team_abc"}
+    cm = ClaimMapping(
+        tenant_id_claim="organization_id",
+        tenant_fallback="sub",  # Would use sub, but org claim wins
+    )
+    service = TokenService(_MockValidator(claims), claim_mapping=cm)
+
+    ctx = service.validate_and_extract("token")
+    assert ctx.tenant is not None
+    assert ctx.tenant.tenant_id == "team_abc"
+    assert ctx.tenant.metadata["resolution"] == "claim"
+
+
+def test_cascade_step3_sub_fallback_metadata() -> None:
+    """Step 3: Sub fallback includes resolution metadata."""
+    claims = {"sub": "solo_user"}
+    cm = ClaimMapping(tenant_fallback="sub")
+    service = TokenService(_MockValidator(claims), claim_mapping=cm)
+
+    ctx = service.validate_and_extract("token")
+    assert ctx.tenant is not None
+    assert ctx.tenant.tenant_id == "solo_user"
+    assert ctx.tenant.metadata["resolution"] == "sub_fallback"
+

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

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