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

{open_shield_python-0.1.0 → open_shield_python-0.2.0}/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.0}/PKG-INFO

@@ -1,21 +1,8 @@
 Metadata-Version: 2.4
 Name: open-shield-python
-Version: 0.1.0
+Version: 0.2.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
@@ -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.0}/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.0}/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.0}/pyproject.toml

@@ -1,25 +1,9 @@
 [project]
 name = "open-shield-python"
-version = "0.1.0"
+version = "0.2.0"
 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.0/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.0/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.0}/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.0}/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.0}/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.0/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.0/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.0/src/open_shield/domain/services/token_service.py

@@ -0,0 +1,114 @@
+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.services.claim_mapping import ClaimMapping
+
+
+class TokenService:
+    """Domain service for orchestrating token validation and context extraction.
+
+    Dependencies are injected via constructor (DIP).
+
+    Args:
+        validator: Port for JWT validation.
+        claim_mapping: Configurable claim-to-field mapping.
+            Defaults to standard OIDC claim names if not provided.
+    """
+
+    def __init__(
+        self,
+        validator: TokenValidatorPort,
+        claim_mapping: ClaimMapping | None = None,
+    ):
+        self.validator = validator
+        self.claims = claim_mapping or ClaimMapping()
+
+    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 from the token.
+
+        Uses the configured tenant_id_claim. Falls back to the
+        configured tenant_fallback strategy if the claim is missing.
+        """
+        tid = token.claims.get(self.claims.tenant_id_claim)
+
+        if not tid and self.claims.tenant_fallback == "sub":
+            tid = token.subject
+
+        if tid:
+            return TenantContext(tenant_id=tid, metadata={})
+
+        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"

open_shield_python-0.2.0/tests/unit/domain/test_claim_mapping.py

@@ -0,0 +1,154 @@
+from typing import Any
+
+from open_shield.domain.entities import Token
+from open_shield.domain.ports import TokenValidatorPort
+from open_shield.domain.services import TokenService
+from open_shield.domain.services.claim_mapping import ClaimMapping
+
+
+class _MockValidator(TokenValidatorPort):
+    """Mock validator that returns a token with given claims."""
+
+    def __init__(self, claims: dict[str, Any]) -> None:
+        self._claims = claims
+
+    def validate_token(self, token_string: str) -> Token:
+        return Token(raw=token_string, claims=self._claims)
+
+    def decode_unverified(self, token_string: str) -> dict[str, Any]:
+        return self._claims
+
+
+# ---------------------------------------------------------------------------
+# Claim Mapping Tests
+# ---------------------------------------------------------------------------
+
+
+def test_default_claim_mapping() -> None:
+    """Default ClaimMapping reads standard OIDC claims."""
+    cm = ClaimMapping()
+    assert cm.user_id_claim == "sub"
+    assert cm.email_claim == "email"
+    assert cm.tenant_id_claim == "tid"
+    assert cm.scope_claim == "scope"
+    assert cm.roles_claim == "roles"
+    assert cm.tenant_fallback == "none"
+
+
+def test_custom_email_claim() -> None:
+    """Email is extracted from a custom claim name."""
+    claims = {"sub": "u1", "preferred_username": "alice@corp.com"}
+    cm = ClaimMapping(email_claim="preferred_username")
+    service = TokenService(_MockValidator(claims), claim_mapping=cm)
+
+    ctx = service.validate_and_extract("token")
+    assert ctx.user.email == "alice@corp.com"
+
+
+def test_custom_tenant_claim_logto() -> None:
+    """Tenant extracted from Logto's organization_id claim."""
+    claims = {"sub": "u1", "organization_id": "org_abc"}
+    cm = ClaimMapping(tenant_id_claim="organization_id")
+    service = TokenService(_MockValidator(claims), claim_mapping=cm)
+
+    ctx = service.validate_and_extract("token")
+    assert ctx.tenant is not None
+    assert ctx.tenant.tenant_id == "org_abc"
+
+
+def test_custom_tenant_claim_keycloak() -> None:
+    """Tenant extracted from Keycloak-style custom claim."""
+    claims = {"sub": "u1", "tenant": "customer_a"}
+    cm = ClaimMapping(tenant_id_claim="tenant")
+    service = TokenService(_MockValidator(claims), claim_mapping=cm)
+
+    ctx = service.validate_and_extract("token")
+    assert ctx.tenant is not None
+    assert ctx.tenant.tenant_id == "customer_a"
+
+
+def test_tenant_fallback_to_sub() -> None:
+    """When tenant claim is missing and fallback='sub', use user ID."""
+    claims = {"sub": "user_123"}
+    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 == "user_123"
+
+
+def test_tenant_fallback_none() -> None:
+    """When tenant claim is missing and fallback='none', tenant is None."""
+    claims = {"sub": "user_123"}
+    cm = ClaimMapping(tenant_fallback="none")
+    service = TokenService(_MockValidator(claims), claim_mapping=cm)
+
+    ctx = service.validate_and_extract("token")
+    assert ctx.tenant is None
+
+
+def test_custom_scope_claim() -> None:
+    """Scopes extracted from a custom claim name."""
+    claims = {"sub": "u1", "permissions": "read write admin"}
+    cm = ClaimMapping(scope_claim="permissions")
+    service = TokenService(_MockValidator(claims), claim_mapping=cm)
+
+    ctx = service.validate_and_extract("token")
+    assert ctx.user.scopes == ["read", "write", "admin"]
+
+
+def test_custom_roles_claim() -> None:
+    """Roles extracted from a custom claim name."""
+    claims = {"sub": "u1", "app_roles": ["editor", "viewer"]}
+    cm = ClaimMapping(roles_claim="app_roles")
+    service = TokenService(_MockValidator(claims), claim_mapping=cm)
+
+    ctx = service.validate_and_extract("token")
+    assert "editor" in ctx.user.roles
+    assert "viewer" in ctx.user.roles
+
+
+# ---------------------------------------------------------------------------
+# Actor Type Inference Tests
+# ---------------------------------------------------------------------------
+
+
+def test_actor_type_user_default() -> None:
+    """Default actor type is 'user' for normal JWT tokens."""
+    claims = {"sub": "user_123", "email": "user@test.com"}
+    service = TokenService(_MockValidator(claims))
+
+    ctx = service.validate_and_extract("token")
+    assert ctx.user.actor_type == "user"
+
+
+def test_actor_type_service_m2m() -> None:
+    """M2M token (sub == client_id) → 'service'."""
+    claims = {"sub": "client_abc", "client_id": "client_abc"}
+    service = TokenService(_MockValidator(claims))
+
+    ctx = service.validate_and_extract("token")
+    assert ctx.user.actor_type == "service"
+
+
+def test_actor_type_agent_m2m() -> None:
+    """M2M token with 'agent' role → 'agent'."""
+    claims = {
+        "sub": "agent_xyz",
+        "client_id": "agent_xyz",
+        "roles": ["agent"],
+    }
+    service = TokenService(_MockValidator(claims))
+
+    ctx = service.validate_and_extract("token")
+    assert ctx.user.actor_type == "agent"
+
+
+def test_actor_type_azp_fallback() -> None:
+    """azp claim used when client_id is absent."""
+    claims = {"sub": "svc_001", "azp": "svc_001"}
+    service = TokenService(_MockValidator(claims))
+
+    ctx = service.validate_and_extract("token")
+    assert ctx.user.actor_type == "service"

open_shield_python-0.1.0/.agent/rules.md

@@ -1,19 +0,0 @@
-# Agent Rules for Open Shield
-
-These rules apply to any AI agent working on this codebase.
-
-## 🛡️ Critical Workflows
-
-1. **Verify Before Push**: 
-   - You MUST run `./scripts/verify.sh` or use the `/safe-commit` workflow before pushing any code to `main` or `staging`.
-   - If verification fails, **DO NOT** push. Fix the errors first.
-
-2. **Clean Architecture**:
-   - Respect the dependency rule: `Domain` <- `Adapters` <- `App/API`.
-   - Domain entities/ports must NOT import from adapters or external frameworks (except generic types).
-
-3. **Conventional Commits**:
-   - Use strict conventional commits (`feat:`, `fix:`, `chore:`, `refactor:`, `docs:`).
-
-4. **Self-Correction**:
-   - If a tool fails (e.g., `ruff` finds errors), attempt to fix it automatically using the tool's suggestions (e.g., `ruff check --fix`) before asking the user, unless the fix is ambiguous.