open-shield-python 0.2.4__tar.gz → 0.2.6__tar.gz

{open_shield_python-0.2.4 → open_shield_python-0.2.6}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: open-shield-python
-Version: 0.2.4
+Version: 0.2.6
 Summary: Vendor-agnostic authentication and authorization enforcement SDK
 Project-URL: Homepage, https://github.com/avinash-singh-io/open-shield-python
 Project-URL: Repository, https://github.com/avinash-singh-io/open-shield-python
 Project-URL: Bug Tracker, https://github.com/avinash-singh-io/open-shield-python/issues
-Author-email: Avinash Singh <avinashsingh539+osp-security@gmail.com>
+Author-email: Avinash Singh <avinashsingh539+osp@gmail.com>
 License: MIT
 License-File: LICENSE
 Keywords: authentication,authorization,fastapi,jwt,oidc,rbac,security
@@ -264,26 +264,32 @@ ctx.user.actor_type  # "user" | "service" | "agent"
 
 ## Architecture
 
-```
-┌─────────────────────────────────────────────────┐
-│  API Layer (FastAPI middleware, dependencies)    │
-├─────────────────────────────────────────────────┤
-│  Domain Layer (pure Python, zero dependencies)  │
-│  ├── Entities: User, Token, TenantContext       │
-│  ├── Services: TokenService, AuthzService       │
-│  ├── Ports: TokenValidatorPort, TenantResolver  │
-│  └── ClaimMapping: configurable extraction      │
-├─────────────────────────────────────────────────┤
-│  Adapters Layer (PyJWT, httpx, OIDC discovery)  │
-└─────────────────────────────────────────────────┘
-```
+Open Shield sits as a **thin, powerful layer** between your identity provider and your Python backend — handling all the complexity of token validation, claim extraction, tenant resolution, and authorization enforcement so you don't have to.
+
+![How Open Shield Works](https://raw.githubusercontent.com/avinash-singh-io/open-shield-python/main/docs/images/architecture.png)
+
+### How It Works
+
+1. **Any OIDC Identity Provider** (Logto, Auth0, Keycloak, Azure Entra ID, AWS Cognito, or your own) issues a JWT token when a user or service authenticates.
+2. **Open Shield SDK** intercepts the incoming request in your Python application and:
+   - **Validates the token** — verifies the signature using auto-fetched JWKS keys from the provider's OIDC discovery endpoint.
+   - **Maps claims** — extracts user ID, email, tenant, scopes, and roles from the JWT using your configurable claim mapping (every provider names claims differently — Open Shield normalizes them).
+   - **Resolves the tenant** — determines tenant isolation using the 3-step cascade (M2M lookup → org claim → sub fallback).
+   - **Detects actor type** — classifies the caller as `user`, `service`, or `agent`.
+   - **Enforces authorization** — checks scopes and roles before the request reaches your handler.
+3. **Your Python service** receives a clean, verified `UserContext` object — ready to use. No JWT parsing, no OIDC plumbing, no provider-specific code.
+
+### Request Authentication Flow
+
+![Request Authentication Flow](https://raw.githubusercontent.com/avinash-singh-io/open-shield-python/main/docs/images/sequence-flow.png)
 
-**Ports (interfaces):**
-- `TokenValidatorPort` — JWT validation
-- `KeyProviderPort` — JWKS key fetching
-- `TenantResolverPort` — M2M client → tenant lookup
+### Why This Matters
 
-All ports are in the domain layer. Adapters implement them in the adapters layer. You can swap implementations without touching application code.
+- **Works with any OIDC provider** — Switch from Auth0 to Keycloak? Change two environment variables. Zero code changes.
+- **Works with any Python framework** — First-class FastAPI support today, with Django and Flask coming soon. The core logic is pure Python with no framework dependency.
+- **Built on Clean Architecture** — The domain layer has zero external dependencies. All I/O (JWT decoding, OIDC discovery) happens through abstract ports implemented by swappable adapters.
+- **Easy to test** — Mock the `TokenValidatorPort` for fast unit tests without any HTTP calls.
+- **Easy to extend** — Implement `TenantResolverPort` to wire in your own database for M2M tenant lookups.
 
 ---
 

{open_shield_python-0.2.4 → open_shield_python-0.2.6}/README.md

@@ -238,26 +238,32 @@ ctx.user.actor_type  # "user" | "service" | "agent"
 
 ## Architecture
 
-```
-┌─────────────────────────────────────────────────┐
-│  API Layer (FastAPI middleware, dependencies)    │
-├─────────────────────────────────────────────────┤
-│  Domain Layer (pure Python, zero dependencies)  │
-│  ├── Entities: User, Token, TenantContext       │
-│  ├── Services: TokenService, AuthzService       │
-│  ├── Ports: TokenValidatorPort, TenantResolver  │
-│  └── ClaimMapping: configurable extraction      │
-├─────────────────────────────────────────────────┤
-│  Adapters Layer (PyJWT, httpx, OIDC discovery)  │
-└─────────────────────────────────────────────────┘
-```
+Open Shield sits as a **thin, powerful layer** between your identity provider and your Python backend — handling all the complexity of token validation, claim extraction, tenant resolution, and authorization enforcement so you don't have to.
+
+![How Open Shield Works](https://raw.githubusercontent.com/avinash-singh-io/open-shield-python/main/docs/images/architecture.png)
+
+### How It Works
+
+1. **Any OIDC Identity Provider** (Logto, Auth0, Keycloak, Azure Entra ID, AWS Cognito, or your own) issues a JWT token when a user or service authenticates.
+2. **Open Shield SDK** intercepts the incoming request in your Python application and:
+   - **Validates the token** — verifies the signature using auto-fetched JWKS keys from the provider's OIDC discovery endpoint.
+   - **Maps claims** — extracts user ID, email, tenant, scopes, and roles from the JWT using your configurable claim mapping (every provider names claims differently — Open Shield normalizes them).
+   - **Resolves the tenant** — determines tenant isolation using the 3-step cascade (M2M lookup → org claim → sub fallback).
+   - **Detects actor type** — classifies the caller as `user`, `service`, or `agent`.
+   - **Enforces authorization** — checks scopes and roles before the request reaches your handler.
+3. **Your Python service** receives a clean, verified `UserContext` object — ready to use. No JWT parsing, no OIDC plumbing, no provider-specific code.
+
+### Request Authentication Flow
+
+![Request Authentication Flow](https://raw.githubusercontent.com/avinash-singh-io/open-shield-python/main/docs/images/sequence-flow.png)
 
-**Ports (interfaces):**
-- `TokenValidatorPort` — JWT validation
-- `KeyProviderPort` — JWKS key fetching
-- `TenantResolverPort` — M2M client → tenant lookup
+### Why This Matters
 
-All ports are in the domain layer. Adapters implement them in the adapters layer. You can swap implementations without touching application code.
+- **Works with any OIDC provider** — Switch from Auth0 to Keycloak? Change two environment variables. Zero code changes.
+- **Works with any Python framework** — First-class FastAPI support today, with Django and Flask coming soon. The core logic is pure Python with no framework dependency.
+- **Built on Clean Architecture** — The domain layer has zero external dependencies. All I/O (JWT decoding, OIDC discovery) happens through abstract ports implemented by swappable adapters.
+- **Easy to test** — Mock the `TokenValidatorPort` for fast unit tests without any HTTP calls.
+- **Easy to extend** — Implement `TenantResolverPort` to wire in your own database for M2M tenant lookups.
 
 ---
 

{open_shield_python-0.2.4 → open_shield_python-0.2.6}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "open-shield-python"
-version = "0.2.4"
+version = "0.2.6"
 description = "Vendor-agnostic authentication and authorization enforcement SDK"
 readme = "README.md"
 requires-python = ">=3.12"
 license = { text = "MIT" }
 authors = [
-    { name = "Avinash Singh", email = "avinashsingh539+osp-security@gmail.com" }
+    { name = "Avinash Singh", email = "avinashsingh539+osp@gmail.com" }
 ]
 keywords = [
     "authentication",