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

open_shield_python-0.2.2/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+avinashsingh539+osp-security@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available
+at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

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

@@ -11,7 +11,7 @@ Thank you for your interest in contributing to Open Shield! We welcome contribut
 
 2. **Clone the repository**:
    ```bash
-   git clone https://github.com/prayog-ai-labs/open-shield-python.git
+   git clone https://github.com/avinash-singh-io/open-shield-python.git
    cd open-shield-python
    ```
 

{open_shield_python-0.2.1 → open_shield_python-0.2.2}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Prayog AI Labs
+Copyright (c) 2026 Avinash Singh
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

open_shield_python-0.2.2/PKG-INFO

@@ -0,0 +1,324 @@
+Metadata-Version: 2.4
+Name: open-shield-python
+Version: 0.2.2
+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>
+License: MIT
+License-File: LICENSE
+Keywords: authentication,authorization,fastapi,jwt,oidc,rbac,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+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
+
+[![CI](https://github.com/avinash-singh-io/open-shield-python/actions/workflows/ci.yml/badge.svg)](https://github.com/avinash-singh-io/open-shield-python/actions/workflows/ci.yml)
+
+Vendor-agnostic authentication and authorization enforcement SDK for Python.
+
+Open Shield lets you enforce authentication (AuthN) and authorization (AuthZ) in your Python applications without coupling to a specific identity provider. Works with **Logto**, **Keycloak**, **Auth0**, **Entra ID**, **Cognito**, or any OIDC-compliant provider.
+
+## Features
+
+- **Vendor Neutral** — Works with any OIDC-compliant identity provider
+- **Configurable Claim Mapping** — Map any JWT claim to user/tenant/role fields
+- **3-Step Tenant Cascade** — Correct isolation for individual users, SaaS orgs, and M2M clients
+- **Actor Type Inference** — Automatically detect users, agents, and service accounts
+- **Framework Agnostic** — Core logic is pure Python; first-class FastAPI support
+- **Clean Architecture** — Domain ↔ Adapters ↔ API layers with strict dependency inversion
+- **Type Safe** — Fully typed, checked with `mypy`
+- **Automatic JWKS Rotation** — Fetches and caches keys from OIDC discovery
+
+## Installation
+
+```bash
+pip install open-shield-python
+```
+
+## Quick Start (FastAPI)
+
+### 1. Configure Environment
+
+```bash
+OPEN_SHIELD_ISSUER_URL=https://your-auth-domain.com/oidc
+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,
+    get_optional_user_context,
+    RequireScope,
+    RequireRole,
+)
+from open_shield.adapters import OpenShieldConfig
+from open_shield.domain.entities import UserContext
+
+app = FastAPI()
+config = OpenShieldConfig()  # Reads from env vars
+
+app.add_middleware(OpenShieldMiddleware, config=config)
+
+@app.get("/health")
+def health():
+    return {"status": "ok"}
+
+@app.get("/users/me")
+def read_current_user(ctx: UserContext = Depends(get_user_context)):
+    return {
+        "id": ctx.user.id,
+        "email": ctx.user.email,
+        "actor_type": ctx.user.actor_type,
+        "tenant": ctx.tenant.tenant_id if ctx.tenant else None,
+        "scopes": ctx.user.scopes,
+        "roles": ctx.user.roles,
+    }
+
+@app.get("/admin/dashboard")
+def admin_dashboard(ctx: UserContext = Depends(RequireScope("read:admin"))):
+    return {"data": "secret"}
+
+@app.get("/manager/reports")
+def reports(ctx: UserContext = Depends(RequireRole(["manager", "admin"]))):
+    return {"reports": []}
+```
+
+---
+
+## Configurable Claim Mapping
+
+Different identity providers use different JWT claim names. Open Shield lets you configure which claims map to which identity fields — **zero code changes** when switching providers.
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OPEN_SHIELD_ISSUER_URL` | OIDC Issuer URL **(required)** | — |
+| `OPEN_SHIELD_AUDIENCE` | Expected `aud` claim | `None` |
+| `OPEN_SHIELD_ALGORITHMS` | Allowed signing algorithms | `["RS256"]` |
+| `OPEN_SHIELD_USER_ID_CLAIM` | Claim for user ID | `sub` |
+| `OPEN_SHIELD_EMAIL_CLAIM` | Claim for email | `email` |
+| `OPEN_SHIELD_TENANT_ID_CLAIM` | Claim for tenant/org ID | `tid` |
+| `OPEN_SHIELD_SCOPE_CLAIM` | Claim for scopes | `scope` |
+| `OPEN_SHIELD_ROLES_CLAIM` | Claim for roles | `roles` |
+| `OPEN_SHIELD_TENANT_FALLBACK` | Fallback when tenant claim missing | `none` |
+
+### Provider Examples
+
+<details>
+<summary><strong>Logto</strong></summary>
+
+```bash
+OPEN_SHIELD_ISSUER_URL=https://my-logto.com/oidc
+OPEN_SHIELD_AUDIENCE=https://my-api.com
+OPEN_SHIELD_TENANT_ID_CLAIM=organization_id
+OPEN_SHIELD_TENANT_FALLBACK=sub    # Individual users get isolation
+```
+</details>
+
+<details>
+<summary><strong>Keycloak</strong></summary>
+
+```bash
+OPEN_SHIELD_ISSUER_URL=https://keycloak.com/realms/myrealm
+OPEN_SHIELD_AUDIENCE=my-client-id
+OPEN_SHIELD_TENANT_ID_CLAIM=tenant     # Custom claim from mapper
+OPEN_SHIELD_ROLES_CLAIM=roles          # Keycloak realm_access also supported
+```
+</details>
+
+<details>
+<summary><strong>Auth0</strong></summary>
+
+```bash
+OPEN_SHIELD_ISSUER_URL=https://my-tenant.auth0.com/
+OPEN_SHIELD_AUDIENCE=https://my-api
+OPEN_SHIELD_TENANT_ID_CLAIM=org_id
+OPEN_SHIELD_SCOPE_CLAIM=permissions    # Auth0 uses 'permissions' for RBAC
+```
+</details>
+
+<details>
+<summary><strong>Azure Entra ID</strong></summary>
+
+```bash
+OPEN_SHIELD_ISSUER_URL=https://login.microsoftonline.com/{tenant-id}/v2.0
+OPEN_SHIELD_AUDIENCE=api://my-api
+OPEN_SHIELD_TENANT_ID_CLAIM=tid
+OPEN_SHIELD_ROLES_CLAIM=roles
+```
+</details>
+
+### Programmatic Configuration
+
+```python
+from open_shield.adapters import OpenShieldConfig
+
+config = OpenShieldConfig(
+    ISSUER_URL="https://my-auth.com/oidc",
+    AUDIENCE="https://my-api",
+    TENANT_ID_CLAIM="organization_id",
+    TENANT_FALLBACK="sub",
+)
+```
+
+---
+
+## Tenant Resolution Cascade
+
+Tenant isolation is critical for data security. Open Shield uses a **3-step cascade** to resolve the tenant for every request — supporting individual users, SaaS organizations, and M2M service accounts.
+
+### How It Works
+
+```
+Step 1: M2M client (sub == client_id)  → TenantResolverPort.resolve_tenant()
+Step 2: Organization claim              → OPEN_SHIELD_TENANT_ID_CLAIM
+Step 3: Sub fallback                    → sub (when TENANT_FALLBACK=sub)
+```
+
+| Use Case | Tenant Source | Config |
+|----------|---------------|--------|
+| Individual user | `sub` | `TENANT_FALLBACK=sub` |
+| SaaS with orgs | `organization_id` | `TENANT_ID_CLAIM=organization_id` |
+| M2M service | Registry lookup | Implement `TenantResolverPort` |
+| No tenant needed | None | `TENANT_FALLBACK=none` (default) |
+
+### When to Use Each Strategy
+
+**Individual users (OSS, personal tools):**
+```bash
+OPEN_SHIELD_TENANT_FALLBACK=sub
+```
+Each user = separate dataset. Simple. Works immediately.
+
+**SaaS with organizations (teams, billing per org):**
+```bash
+OPEN_SHIELD_TENANT_ID_CLAIM=organization_id
+OPEN_SHIELD_TENANT_FALLBACK=none        # Don't fall back to sub
+```
+Multiple users share org data. Required for team features.
+
+**M2M / AI agents (client_credentials flow):**
+```python
+from open_shield.domain.ports import TenantResolverPort
+
+class MyTenantResolver(TenantResolverPort):
+    """Look up tenant for machine clients from your registry."""
+
+    def resolve_tenant(self, client_id: str) -> str | None:
+        # Query your DB, config, or IdP management API
+        return db.get_tenant_for_client(client_id)
+
+# Pass resolver to middleware
+config = OpenShieldConfig(...)
+app.add_middleware(
+    OpenShieldMiddleware,
+    config=config,
+    tenant_resolver=MyTenantResolver(),
+)
+```
+
+### Resolution Metadata
+
+Every resolved tenant includes traceability:
+
+```python
+ctx.tenant.metadata["resolution"]  # "m2m_lookup" | "claim" | "sub_fallback"
+```
+
+---
+
+## Actor Type Inference
+
+Open Shield automatically classifies the caller:
+
+| Actor Type | Detection | Example |
+|------------|-----------|---------|
+| `user` | Default for human tokens | Normal login flow |
+| `service` | `sub == client_id` | M2M client_credentials |
+| `agent` | `sub == client_id` + `"agent"` role | AI agent with agent role |
+
+```python
+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)  │
+└─────────────────────────────────────────────────┘
+```
+
+**Ports (interfaces):**
+- `TokenValidatorPort` — JWT validation
+- `KeyProviderPort` — JWKS key fetching
+- `TenantResolverPort` — M2M client → tenant lookup
+
+All ports are in the domain layer. Adapters implement them in the adapters layer. You can swap implementations without touching application code.
+
+---
+
+## Optional Authentication
+
+For routes that work with or without auth (e.g., public APIs with enhanced features for logged-in users):
+
+```python
+from open_shield.api.fastapi import get_optional_user_context
+
+@app.get("/search")
+def search(ctx: UserContext | None = Depends(get_optional_user_context)):
+    if ctx:
+        return personalized_results(ctx.user.id)
+    return public_results()
+```
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Lint and format
+uv run ruff check .
+
+# Type check
+uv run mypy src/
+```
+
+## License
+
+MIT

open_shield_python-0.2.2/README.md

@@ -0,0 +1,298 @@
+# Open Shield Python SDK
+
+[![CI](https://github.com/avinash-singh-io/open-shield-python/actions/workflows/ci.yml/badge.svg)](https://github.com/avinash-singh-io/open-shield-python/actions/workflows/ci.yml)
+
+Vendor-agnostic authentication and authorization enforcement SDK for Python.
+
+Open Shield lets you enforce authentication (AuthN) and authorization (AuthZ) in your Python applications without coupling to a specific identity provider. Works with **Logto**, **Keycloak**, **Auth0**, **Entra ID**, **Cognito**, or any OIDC-compliant provider.
+
+## Features
+
+- **Vendor Neutral** — Works with any OIDC-compliant identity provider
+- **Configurable Claim Mapping** — Map any JWT claim to user/tenant/role fields
+- **3-Step Tenant Cascade** — Correct isolation for individual users, SaaS orgs, and M2M clients
+- **Actor Type Inference** — Automatically detect users, agents, and service accounts
+- **Framework Agnostic** — Core logic is pure Python; first-class FastAPI support
+- **Clean Architecture** — Domain ↔ Adapters ↔ API layers with strict dependency inversion
+- **Type Safe** — Fully typed, checked with `mypy`
+- **Automatic JWKS Rotation** — Fetches and caches keys from OIDC discovery
+
+## Installation
+
+```bash
+pip install open-shield-python
+```
+
+## Quick Start (FastAPI)
+
+### 1. Configure Environment
+
+```bash
+OPEN_SHIELD_ISSUER_URL=https://your-auth-domain.com/oidc
+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,
+    get_optional_user_context,
+    RequireScope,
+    RequireRole,
+)
+from open_shield.adapters import OpenShieldConfig
+from open_shield.domain.entities import UserContext
+
+app = FastAPI()
+config = OpenShieldConfig()  # Reads from env vars
+
+app.add_middleware(OpenShieldMiddleware, config=config)
+
+@app.get("/health")
+def health():
+    return {"status": "ok"}
+
+@app.get("/users/me")
+def read_current_user(ctx: UserContext = Depends(get_user_context)):
+    return {
+        "id": ctx.user.id,
+        "email": ctx.user.email,
+        "actor_type": ctx.user.actor_type,
+        "tenant": ctx.tenant.tenant_id if ctx.tenant else None,
+        "scopes": ctx.user.scopes,
+        "roles": ctx.user.roles,
+    }
+
+@app.get("/admin/dashboard")
+def admin_dashboard(ctx: UserContext = Depends(RequireScope("read:admin"))):
+    return {"data": "secret"}
+
+@app.get("/manager/reports")
+def reports(ctx: UserContext = Depends(RequireRole(["manager", "admin"]))):
+    return {"reports": []}
+```
+
+---
+
+## Configurable Claim Mapping
+
+Different identity providers use different JWT claim names. Open Shield lets you configure which claims map to which identity fields — **zero code changes** when switching providers.
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OPEN_SHIELD_ISSUER_URL` | OIDC Issuer URL **(required)** | — |
+| `OPEN_SHIELD_AUDIENCE` | Expected `aud` claim | `None` |
+| `OPEN_SHIELD_ALGORITHMS` | Allowed signing algorithms | `["RS256"]` |
+| `OPEN_SHIELD_USER_ID_CLAIM` | Claim for user ID | `sub` |
+| `OPEN_SHIELD_EMAIL_CLAIM` | Claim for email | `email` |
+| `OPEN_SHIELD_TENANT_ID_CLAIM` | Claim for tenant/org ID | `tid` |
+| `OPEN_SHIELD_SCOPE_CLAIM` | Claim for scopes | `scope` |
+| `OPEN_SHIELD_ROLES_CLAIM` | Claim for roles | `roles` |
+| `OPEN_SHIELD_TENANT_FALLBACK` | Fallback when tenant claim missing | `none` |
+
+### Provider Examples
+
+<details>
+<summary><strong>Logto</strong></summary>
+
+```bash
+OPEN_SHIELD_ISSUER_URL=https://my-logto.com/oidc
+OPEN_SHIELD_AUDIENCE=https://my-api.com
+OPEN_SHIELD_TENANT_ID_CLAIM=organization_id
+OPEN_SHIELD_TENANT_FALLBACK=sub    # Individual users get isolation
+```
+</details>
+
+<details>
+<summary><strong>Keycloak</strong></summary>
+
+```bash
+OPEN_SHIELD_ISSUER_URL=https://keycloak.com/realms/myrealm
+OPEN_SHIELD_AUDIENCE=my-client-id
+OPEN_SHIELD_TENANT_ID_CLAIM=tenant     # Custom claim from mapper
+OPEN_SHIELD_ROLES_CLAIM=roles          # Keycloak realm_access also supported
+```
+</details>
+
+<details>
+<summary><strong>Auth0</strong></summary>
+
+```bash
+OPEN_SHIELD_ISSUER_URL=https://my-tenant.auth0.com/
+OPEN_SHIELD_AUDIENCE=https://my-api
+OPEN_SHIELD_TENANT_ID_CLAIM=org_id
+OPEN_SHIELD_SCOPE_CLAIM=permissions    # Auth0 uses 'permissions' for RBAC
+```
+</details>
+
+<details>
+<summary><strong>Azure Entra ID</strong></summary>
+
+```bash
+OPEN_SHIELD_ISSUER_URL=https://login.microsoftonline.com/{tenant-id}/v2.0
+OPEN_SHIELD_AUDIENCE=api://my-api
+OPEN_SHIELD_TENANT_ID_CLAIM=tid
+OPEN_SHIELD_ROLES_CLAIM=roles
+```
+</details>
+
+### Programmatic Configuration
+
+```python
+from open_shield.adapters import OpenShieldConfig
+
+config = OpenShieldConfig(
+    ISSUER_URL="https://my-auth.com/oidc",
+    AUDIENCE="https://my-api",
+    TENANT_ID_CLAIM="organization_id",
+    TENANT_FALLBACK="sub",
+)
+```
+
+---
+
+## Tenant Resolution Cascade
+
+Tenant isolation is critical for data security. Open Shield uses a **3-step cascade** to resolve the tenant for every request — supporting individual users, SaaS organizations, and M2M service accounts.
+
+### How It Works
+
+```
+Step 1: M2M client (sub == client_id)  → TenantResolverPort.resolve_tenant()
+Step 2: Organization claim              → OPEN_SHIELD_TENANT_ID_CLAIM
+Step 3: Sub fallback                    → sub (when TENANT_FALLBACK=sub)
+```
+
+| Use Case | Tenant Source | Config |
+|----------|---------------|--------|
+| Individual user | `sub` | `TENANT_FALLBACK=sub` |
+| SaaS with orgs | `organization_id` | `TENANT_ID_CLAIM=organization_id` |
+| M2M service | Registry lookup | Implement `TenantResolverPort` |
+| No tenant needed | None | `TENANT_FALLBACK=none` (default) |
+
+### When to Use Each Strategy
+
+**Individual users (OSS, personal tools):**
+```bash
+OPEN_SHIELD_TENANT_FALLBACK=sub
+```
+Each user = separate dataset. Simple. Works immediately.
+
+**SaaS with organizations (teams, billing per org):**
+```bash
+OPEN_SHIELD_TENANT_ID_CLAIM=organization_id
+OPEN_SHIELD_TENANT_FALLBACK=none        # Don't fall back to sub
+```
+Multiple users share org data. Required for team features.
+
+**M2M / AI agents (client_credentials flow):**
+```python
+from open_shield.domain.ports import TenantResolverPort
+
+class MyTenantResolver(TenantResolverPort):
+    """Look up tenant for machine clients from your registry."""
+
+    def resolve_tenant(self, client_id: str) -> str | None:
+        # Query your DB, config, or IdP management API
+        return db.get_tenant_for_client(client_id)
+
+# Pass resolver to middleware
+config = OpenShieldConfig(...)
+app.add_middleware(
+    OpenShieldMiddleware,
+    config=config,
+    tenant_resolver=MyTenantResolver(),
+)
+```
+
+### Resolution Metadata
+
+Every resolved tenant includes traceability:
+
+```python
+ctx.tenant.metadata["resolution"]  # "m2m_lookup" | "claim" | "sub_fallback"
+```
+
+---
+
+## Actor Type Inference
+
+Open Shield automatically classifies the caller:
+
+| Actor Type | Detection | Example |
+|------------|-----------|---------|
+| `user` | Default for human tokens | Normal login flow |
+| `service` | `sub == client_id` | M2M client_credentials |
+| `agent` | `sub == client_id` + `"agent"` role | AI agent with agent role |
+
+```python
+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)  │
+└─────────────────────────────────────────────────┘
+```
+
+**Ports (interfaces):**
+- `TokenValidatorPort` — JWT validation
+- `KeyProviderPort` — JWKS key fetching
+- `TenantResolverPort` — M2M client → tenant lookup
+
+All ports are in the domain layer. Adapters implement them in the adapters layer. You can swap implementations without touching application code.
+
+---
+
+## Optional Authentication
+
+For routes that work with or without auth (e.g., public APIs with enhanced features for logged-in users):
+
+```python
+from open_shield.api.fastapi import get_optional_user_context
+
+@app.get("/search")
+def search(ctx: UserContext | None = Depends(get_optional_user_context)):
+    if ctx:
+        return personalized_results(ctx.user.id)
+    return public_results()
+```
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Lint and format
+uv run ruff check .
+
+# Type check
+uv run mypy src/
+```
+
+## License
+
+MIT

open_shield_python-0.2.2/SECURITY.md

@@ -0,0 +1,20 @@
+# Security Policy
+
+## Supported Versions
+
+Currently, the `main` branch and the latest published PyPI release are supported for security updates.
+
+## Reporting a Vulnerability
+
+We take the security of Open Shield very seriously. If you discover a vulnerability, please do NOT use the issue tracker to report it publicly.
+
+Instead, please send an email to: **avinashsingh539+osp-security@gmail.com**
+
+Please provide as much information as possible, including:
+
+- A description of the vulnerability.
+- Steps to reproduce it.
+- Possible impact or attack vector.
+- Your contact information for follow-up.
+
+We will acknowledge receipt of your report within 48 hours and provide an estimated timeline for a fix. Once the vulnerability is patched, we will coordinate public disclosure.

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

@@ -1,9 +1,30 @@
 [project]
 name = "open-shield-python"
-version = "0.2.1"
+version = "0.2.2"
 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" }
+]
+keywords = [
+    "authentication",
+    "authorization",
+    "fastapi",
+    "jwt",
+    "oidc",
+    "rbac",
+    "security"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
 dependencies = [
     "pydantic>=2.0.0",
     "pydantic-settings>=2.0.0",
@@ -52,3 +73,8 @@ dev = [
     "ruff>=0.15.0",
     "uvicorn>=0.40.0",
 ]
+
+[project.urls]
+Homepage = "https://github.com/avinash-singh-io/open-shield-python"
+Repository = "https://github.com/avinash-singh-io/open-shield-python"
+"Bug Tracker" = "https://github.com/avinash-singh-io/open-shield-python/issues"

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

@@ -4,6 +4,7 @@ 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.ports import TenantResolverPort
 from open_shield.domain.services import TokenService
 from open_shield.domain.services.claim_mapping import ClaimMapping
 
@@ -27,6 +28,7 @@ class OpenShieldMiddleware(BaseHTTPMiddleware):
         app: ASGIApp,
         config: OpenShieldConfig,
         exclude_paths: set[str] | None = None,
+        tenant_resolver: TenantResolverPort | None = None,
     ):
         super().__init__(app)
         self.config = config
@@ -58,6 +60,7 @@ class OpenShieldMiddleware(BaseHTTPMiddleware):
         self.token_service = TokenService(
             validator=validator,
             claim_mapping=claim_mapping,
+            tenant_resolver=tenant_resolver,
         )
 
     async def dispatch(

open_shield_python-0.2.1/PKG-INFO

@@ -1,119 +0,0 @@
-Metadata-Version: 2.4
-Name: open-shield-python
-Version: 0.2.1
-Summary: Vendor-agnostic authentication and authorization enforcement SDK
-License-File: LICENSE
-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
-
-[![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).
-
-## 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.2.1/README.md

@@ -1,105 +0,0 @@
-# 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).
-
-## 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 .
-```