auth-gate 0.2.3__tar.gz → 0.3.0__tar.gz

{auth_gate-0.2.3/src/auth_gate.egg-info → auth_gate-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: auth-gate
-Version: 0.2.3
-Summary: Enterprise-grade authentication for microservices with Kong and Keycloak integration
+Version: 0.3.0
+Summary: Enterprise-grade authentication for microservices with Kong/Keycloak integration and subscription tier support
 Home-page: https://github.com/tradelink-org/auth-gate
 Author: Brian Mburu
 Author-email: Brian Mburu <brian.mburu@students.jkuat.ac.ke>
@@ -41,12 +41,13 @@ Dynamic: license-file
 
 # Auth Gate
 
-Enterprise-grade authentication for microservices with Kong and Keycloak integration, supporting both user and service-to-service authentication.
+Enterprise-grade authentication for microservices with Kong and Keycloak integration, supporting user authentication, service-to-service authentication, and subscription tier enforcement.
 
 ## Features
 
 -   **Dual authentication types**: Support for both user authentication and service-to-service authentication
 -   **Unified authentication flow**: Single middleware handles both user and service tokens seamlessly
+-   **Subscription tier enforcement**: Built-in support for FREE, BASIC, PROFESSIONAL, and ENTERPRISE tiers
 -   **Flexible endpoint protection**: Configure endpoints as user-only, service-only, or accessible by both
 -   **Dual-mode authentication**: Support for both Kong header-based auth (production) and direct Keycloak validation (development)
 -   **Service-to-service authentication**: Built-in client credentials flow for secure inter-service communication
@@ -55,6 +56,7 @@ Enterprise-grade authentication for microservices with Kong and Keycloak integra
 -   **FastAPI integration**: Ready-to-use dependencies for protecting endpoints
 -   **Role-based access control**: Fine-grained permission management with role and scope validation for both users and services
 -   **Middleware support**: Automatic request authentication with configurable exclusions
+-   **Organization context**: Multi-tenant support with organization ID tracking
 
 ## Installation
 
@@ -136,6 +138,44 @@ async def get_data(auth: AuthContext = Depends(get_current_auth)):
         return {"data": "full", "service": auth.service_name}
 ```
 
+### Subscription Tier Enforcement
+
+```python
+from auth_gate import (
+    require_tier,
+    require_tier_and_active,
+    require_basic,
+    require_professional,
+    require_enterprise,
+    require_paid_subscription,
+    SubscriptionTier,
+)
+
+# Require minimum tier (PROFESSIONAL or higher)
+@app.get("/api/analytics/advanced")
+async def get_advanced_analytics(
+    auth: AuthContext = Depends(require_tier(SubscriptionTier.PROFESSIONAL))
+):
+    return {"data": "advanced analytics"}
+
+# Convenience dependency for common tiers
+@app.get("/api/reports/enterprise")
+async def get_enterprise_reports(auth: AuthContext = Depends(require_enterprise)):
+    return {"reports": [...]}
+
+# Require both minimum tier AND active subscription
+@app.get("/api/premium/dashboard")
+async def get_premium_dashboard(
+    auth: AuthContext = Depends(require_tier_and_active(SubscriptionTier.BASIC))
+):
+    return {"dashboard": "premium data"}
+
+# Require any paid subscription (non-free)
+@app.get("/api/paid-feature")
+async def get_paid_feature(auth: AuthContext = Depends(require_paid_subscription)):
+    return {"feature": "paid-only data"}
+```
+
 ### Role-Based Access Control
 
 ```python
@@ -214,6 +254,16 @@ VERIFY_HMAC=false
 INTERNAL_HMAC_KEY=your-hmac-key
 ```
 
+### Kong Headers for Subscription
+
+When using Kong, configure the Token Introspector plugin to inject these subscription headers:
+
+| Header                  | Description                    | Example Values                          |
+| ----------------------- | ------------------------------ | --------------------------------------- |
+| `X-Subscription-Tier`   | User's subscription tier       | `free`, `basic`, `professional`, `enterprise` |
+| `X-Subscription-Status` | Subscription status            | `active`, `suspended`, `cancelled`, `past_due` |
+| `X-Organization-ID`     | Organization identifier        | `org-12345`                             |
+
 ## Service-to-Service Authentication
 
 ### Making Service Calls
@@ -379,14 +429,17 @@ The S2S auth client includes automatic circuit breaker protection:
 
 ```python
 class UserContext:
-    user_id: str              # Unique user identifier
-    username: str | None      # Username
-    email: str | None         # Email address
-    roles: List[str]          # User roles
-    scopes: List[str]         # OAuth scopes
-    session_id: str | None    # Session identifier
-    client_id: str | None     # OAuth client ID
-    auth_source: str          # Authentication source
+    user_id: str                        # Unique user identifier
+    username: str | None                # Username
+    email: str | None                   # Email address
+    roles: List[str]                    # User roles
+    scopes: List[str]                   # OAuth scopes
+    session_id: str | None              # Session identifier
+    client_id: str | None               # OAuth client ID
+    auth_source: str                    # Authentication source
+    organization_id: str | None         # Organization identifier
+    subscription_tier: SubscriptionTier # Subscription tier (FREE, BASIC, PROFESSIONAL, ENTERPRISE)
+    subscription_status: SubscriptionStatus  # Status (ACTIVE, SUSPENDED, CANCELLED, PAST_DUE)
 
     # Properties
     is_service: bool          # Always False for users
@@ -394,6 +447,9 @@ class UserContext:
     is_supplier: bool         # True if has supplier role
     is_customer: bool         # True if has customer role
     is_moderator: bool        # True if has moderator role
+    is_buyer: bool            # True if has buyer or customer role
+    is_subscription_active: bool  # True if subscription status is ACTIVE
+    is_paid_subscriber: bool  # True if tier is not FREE
 
     # Methods
     has_role(role: str) -> bool
@@ -401,18 +457,23 @@ class UserContext:
     has_all_roles(roles: List[str]) -> bool
     has_scope(scope: str) -> bool
     has_any_scope(scopes: List[str]) -> bool
+    has_minimum_tier(required_tier: SubscriptionTier) -> bool
+    can_access_feature(required_tier: SubscriptionTier) -> bool
 ```
 
 ### ServiceContext
 
 ```python
 class ServiceContext:
-    service_name: str         # Service identifier (client_id)
-    service_id: str | None    # Service sub claim
-    roles: List[str]          # Service roles
-    session_id: str | None    # Session identifier
-    client_id: str | None     # OAuth client ID
-    auth_source: str          # Authentication source
+    service_name: str                   # Service identifier (client_id)
+    service_id: str | None              # Service sub claim
+    roles: List[str]                    # Service roles
+    session_id: str | None              # Session identifier
+    client_id: str | None               # OAuth client ID
+    auth_source: str                    # Authentication source
+    organization_id: str | None         # Organization identifier
+    subscription_tier: SubscriptionTier # Defaults to FREE (services bypass tier checks)
+    subscription_status: SubscriptionStatus  # Defaults to ACTIVE
 
     # Properties
     is_service: bool          # Always True for services
@@ -424,6 +485,8 @@ class ServiceContext:
     has_all_roles(roles: List[str]) -> bool
 ```
 
+**Note:** Services bypass subscription tier checks by default when using `require_tier()` and related dependencies.
+
 ## Available Dependencies
 
 ### Authentication Dependencies
@@ -462,6 +525,59 @@ require_service_roles("role1", "role2", ...)
 require_scopes("scope1", "scope2", ...)
 ```
 
+### Subscription Dependencies
+
+| Dependency                    | Description                                         |
+| ----------------------------- | --------------------------------------------------- |
+| `require_tier(tier)`          | Factory requiring minimum subscription tier         |
+| `require_active_subscription()` | Factory requiring active subscription status      |
+| `require_tier_and_active(tier)` | Factory requiring both tier and active status     |
+| `require_basic`               | Requires BASIC tier or higher                       |
+| `require_professional`        | Requires PROFESSIONAL tier or higher                |
+| `require_enterprise`          | Requires ENTERPRISE tier                            |
+| `require_paid_subscription`   | Requires any paid tier (non-FREE)                   |
+| `get_subscription_tier`       | Extract tier from header                            |
+| `get_organization_id`         | Extract organization ID from header                 |
+
+### Subscription Types
+
+```python
+from auth_gate import SubscriptionTier, SubscriptionStatus
+
+# Tier hierarchy (lowest to highest)
+SubscriptionTier.FREE
+SubscriptionTier.BASIC
+SubscriptionTier.PROFESSIONAL
+SubscriptionTier.ENTERPRISE
+
+# Subscription statuses
+SubscriptionStatus.ACTIVE
+SubscriptionStatus.SUSPENDED
+SubscriptionStatus.CANCELLED
+SubscriptionStatus.PAST_DUE
+```
+
+### Subscription Utilities
+
+```python
+from auth_gate import (
+    meets_minimum_tier,
+    compare_tiers,
+    is_paid_tier,
+    get_tier_level,
+)
+
+# Check if user tier meets requirement
+meets_minimum_tier(SubscriptionTier.PROFESSIONAL, SubscriptionTier.BASIC)  # True
+
+# Compare tiers (-1, 0, 1)
+compare_tiers(SubscriptionTier.ENTERPRISE, SubscriptionTier.FREE)  # > 0
+
+# Check if tier is paid
+is_paid_tier(SubscriptionTier.BASIC)  # True
+is_paid_tier(SubscriptionTier.FREE)   # False
+```
+
 ## Migration Guide
 
 ### Updating Existing Applications
@@ -529,11 +645,15 @@ from auth_gate import (
     AuthContext,
     UserContext,
     ServiceContext,
+    SubscriptionTier,
     get_current_auth,
     get_current_user,
     get_current_service,
     require_roles,
     require_user_roles,
+    require_tier,
+    require_tier_and_active,
+    require_professional,
 )
 
 app = FastAPI()
@@ -552,7 +672,11 @@ async def health():
 # User-only endpoint
 @app.get("/api/user/profile")
 async def get_profile(user: UserContext = Depends(get_current_user)):
-    return {"user": user.user_id}
+    return {
+        "user": user.user_id,
+        "tier": user.subscription_tier.value,
+        "organization": user.organization_id
+    }
 
 # Service-only endpoint
 @app.post("/api/internal/batch")
@@ -573,6 +697,31 @@ require_user_editor = require_user_roles("editor")
 @app.post("/api/articles")
 async def create_article(user: UserContext = Depends(require_user_editor)):
     return {"author": user.user_id}
+
+# Tier-protected endpoint (PROFESSIONAL or higher)
+@app.get("/api/analytics")
+async def get_analytics(auth: AuthContext = Depends(require_professional)):
+    return {"analytics": "professional data"}
+
+# Tier and active subscription required
+@app.get("/api/premium/reports")
+async def get_premium_reports(
+    auth: AuthContext = Depends(require_tier_and_active(SubscriptionTier.BASIC))
+):
+    return {"reports": "premium data"}
+
+# Custom tier check within endpoint
+@app.get("/api/features")
+async def get_features(user: UserContext = Depends(get_current_user)):
+    features = ["basic_dashboard"]
+
+    if user.has_minimum_tier(SubscriptionTier.PROFESSIONAL):
+        features.append("advanced_analytics")
+
+    if user.has_minimum_tier(SubscriptionTier.ENTERPRISE):
+        features.append("custom_integrations")
+
+    return {"features": features, "tier": user.subscription_tier.value}
 ```
 
 ## License

{auth_gate-0.2.3 → auth_gate-0.3.0}/README.md

@@ -1,11 +1,12 @@
 # Auth Gate
 
-Enterprise-grade authentication for microservices with Kong and Keycloak integration, supporting both user and service-to-service authentication.
+Enterprise-grade authentication for microservices with Kong and Keycloak integration, supporting user authentication, service-to-service authentication, and subscription tier enforcement.
 
 ## Features
 
 -   **Dual authentication types**: Support for both user authentication and service-to-service authentication
 -   **Unified authentication flow**: Single middleware handles both user and service tokens seamlessly
+-   **Subscription tier enforcement**: Built-in support for FREE, BASIC, PROFESSIONAL, and ENTERPRISE tiers
 -   **Flexible endpoint protection**: Configure endpoints as user-only, service-only, or accessible by both
 -   **Dual-mode authentication**: Support for both Kong header-based auth (production) and direct Keycloak validation (development)
 -   **Service-to-service authentication**: Built-in client credentials flow for secure inter-service communication
@@ -14,6 +15,7 @@ Enterprise-grade authentication for microservices with Kong and Keycloak integra
 -   **FastAPI integration**: Ready-to-use dependencies for protecting endpoints
 -   **Role-based access control**: Fine-grained permission management with role and scope validation for both users and services
 -   **Middleware support**: Automatic request authentication with configurable exclusions
+-   **Organization context**: Multi-tenant support with organization ID tracking
 
 ## Installation
 
@@ -95,6 +97,44 @@ async def get_data(auth: AuthContext = Depends(get_current_auth)):
         return {"data": "full", "service": auth.service_name}
 ```
 
+### Subscription Tier Enforcement
+
+```python
+from auth_gate import (
+    require_tier,
+    require_tier_and_active,
+    require_basic,
+    require_professional,
+    require_enterprise,
+    require_paid_subscription,
+    SubscriptionTier,
+)
+
+# Require minimum tier (PROFESSIONAL or higher)
+@app.get("/api/analytics/advanced")
+async def get_advanced_analytics(
+    auth: AuthContext = Depends(require_tier(SubscriptionTier.PROFESSIONAL))
+):
+    return {"data": "advanced analytics"}
+
+# Convenience dependency for common tiers
+@app.get("/api/reports/enterprise")
+async def get_enterprise_reports(auth: AuthContext = Depends(require_enterprise)):
+    return {"reports": [...]}
+
+# Require both minimum tier AND active subscription
+@app.get("/api/premium/dashboard")
+async def get_premium_dashboard(
+    auth: AuthContext = Depends(require_tier_and_active(SubscriptionTier.BASIC))
+):
+    return {"dashboard": "premium data"}
+
+# Require any paid subscription (non-free)
+@app.get("/api/paid-feature")
+async def get_paid_feature(auth: AuthContext = Depends(require_paid_subscription)):
+    return {"feature": "paid-only data"}
+```
+
 ### Role-Based Access Control
 
 ```python
@@ -173,6 +213,16 @@ VERIFY_HMAC=false
 INTERNAL_HMAC_KEY=your-hmac-key
 ```
 
+### Kong Headers for Subscription
+
+When using Kong, configure the Token Introspector plugin to inject these subscription headers:
+
+| Header                  | Description                    | Example Values                          |
+| ----------------------- | ------------------------------ | --------------------------------------- |
+| `X-Subscription-Tier`   | User's subscription tier       | `free`, `basic`, `professional`, `enterprise` |
+| `X-Subscription-Status` | Subscription status            | `active`, `suspended`, `cancelled`, `past_due` |
+| `X-Organization-ID`     | Organization identifier        | `org-12345`                             |
+
 ## Service-to-Service Authentication
 
 ### Making Service Calls
@@ -338,14 +388,17 @@ The S2S auth client includes automatic circuit breaker protection:
 
 ```python
 class UserContext:
-    user_id: str              # Unique user identifier
-    username: str | None      # Username
-    email: str | None         # Email address
-    roles: List[str]          # User roles
-    scopes: List[str]         # OAuth scopes
-    session_id: str | None    # Session identifier
-    client_id: str | None     # OAuth client ID
-    auth_source: str          # Authentication source
+    user_id: str                        # Unique user identifier
+    username: str | None                # Username
+    email: str | None                   # Email address
+    roles: List[str]                    # User roles
+    scopes: List[str]                   # OAuth scopes
+    session_id: str | None              # Session identifier
+    client_id: str | None               # OAuth client ID
+    auth_source: str                    # Authentication source
+    organization_id: str | None         # Organization identifier
+    subscription_tier: SubscriptionTier # Subscription tier (FREE, BASIC, PROFESSIONAL, ENTERPRISE)
+    subscription_status: SubscriptionStatus  # Status (ACTIVE, SUSPENDED, CANCELLED, PAST_DUE)
 
     # Properties
     is_service: bool          # Always False for users
@@ -353,6 +406,9 @@ class UserContext:
     is_supplier: bool         # True if has supplier role
     is_customer: bool         # True if has customer role
     is_moderator: bool        # True if has moderator role
+    is_buyer: bool            # True if has buyer or customer role
+    is_subscription_active: bool  # True if subscription status is ACTIVE
+    is_paid_subscriber: bool  # True if tier is not FREE
 
     # Methods
     has_role(role: str) -> bool
@@ -360,18 +416,23 @@ class UserContext:
     has_all_roles(roles: List[str]) -> bool
     has_scope(scope: str) -> bool
     has_any_scope(scopes: List[str]) -> bool
+    has_minimum_tier(required_tier: SubscriptionTier) -> bool
+    can_access_feature(required_tier: SubscriptionTier) -> bool
 ```
 
 ### ServiceContext
 
 ```python
 class ServiceContext:
-    service_name: str         # Service identifier (client_id)
-    service_id: str | None    # Service sub claim
-    roles: List[str]          # Service roles
-    session_id: str | None    # Session identifier
-    client_id: str | None     # OAuth client ID
-    auth_source: str          # Authentication source
+    service_name: str                   # Service identifier (client_id)
+    service_id: str | None              # Service sub claim
+    roles: List[str]                    # Service roles
+    session_id: str | None              # Session identifier
+    client_id: str | None               # OAuth client ID
+    auth_source: str                    # Authentication source
+    organization_id: str | None         # Organization identifier
+    subscription_tier: SubscriptionTier # Defaults to FREE (services bypass tier checks)
+    subscription_status: SubscriptionStatus  # Defaults to ACTIVE
 
     # Properties
     is_service: bool          # Always True for services
@@ -383,6 +444,8 @@ class ServiceContext:
     has_all_roles(roles: List[str]) -> bool
 ```
 
+**Note:** Services bypass subscription tier checks by default when using `require_tier()` and related dependencies.
+
 ## Available Dependencies
 
 ### Authentication Dependencies
@@ -421,6 +484,59 @@ require_service_roles("role1", "role2", ...)
 require_scopes("scope1", "scope2", ...)
 ```
 
+### Subscription Dependencies
+
+| Dependency                    | Description                                         |
+| ----------------------------- | --------------------------------------------------- |
+| `require_tier(tier)`          | Factory requiring minimum subscription tier         |
+| `require_active_subscription()` | Factory requiring active subscription status      |
+| `require_tier_and_active(tier)` | Factory requiring both tier and active status     |
+| `require_basic`               | Requires BASIC tier or higher                       |
+| `require_professional`        | Requires PROFESSIONAL tier or higher                |
+| `require_enterprise`          | Requires ENTERPRISE tier                            |
+| `require_paid_subscription`   | Requires any paid tier (non-FREE)                   |
+| `get_subscription_tier`       | Extract tier from header                            |
+| `get_organization_id`         | Extract organization ID from header                 |
+
+### Subscription Types
+
+```python
+from auth_gate import SubscriptionTier, SubscriptionStatus
+
+# Tier hierarchy (lowest to highest)
+SubscriptionTier.FREE
+SubscriptionTier.BASIC
+SubscriptionTier.PROFESSIONAL
+SubscriptionTier.ENTERPRISE
+
+# Subscription statuses
+SubscriptionStatus.ACTIVE
+SubscriptionStatus.SUSPENDED
+SubscriptionStatus.CANCELLED
+SubscriptionStatus.PAST_DUE
+```
+
+### Subscription Utilities
+
+```python
+from auth_gate import (
+    meets_minimum_tier,
+    compare_tiers,
+    is_paid_tier,
+    get_tier_level,
+)
+
+# Check if user tier meets requirement
+meets_minimum_tier(SubscriptionTier.PROFESSIONAL, SubscriptionTier.BASIC)  # True
+
+# Compare tiers (-1, 0, 1)
+compare_tiers(SubscriptionTier.ENTERPRISE, SubscriptionTier.FREE)  # > 0
+
+# Check if tier is paid
+is_paid_tier(SubscriptionTier.BASIC)  # True
+is_paid_tier(SubscriptionTier.FREE)   # False
+```
+
 ## Migration Guide
 
 ### Updating Existing Applications
@@ -488,11 +604,15 @@ from auth_gate import (
     AuthContext,
     UserContext,
     ServiceContext,
+    SubscriptionTier,
     get_current_auth,
     get_current_user,
     get_current_service,
     require_roles,
     require_user_roles,
+    require_tier,
+    require_tier_and_active,
+    require_professional,
 )
 
 app = FastAPI()
@@ -511,7 +631,11 @@ async def health():
 # User-only endpoint
 @app.get("/api/user/profile")
 async def get_profile(user: UserContext = Depends(get_current_user)):
-    return {"user": user.user_id}
+    return {
+        "user": user.user_id,
+        "tier": user.subscription_tier.value,
+        "organization": user.organization_id
+    }
 
 # Service-only endpoint
 @app.post("/api/internal/batch")
@@ -532,6 +656,31 @@ require_user_editor = require_user_roles("editor")
 @app.post("/api/articles")
 async def create_article(user: UserContext = Depends(require_user_editor)):
     return {"author": user.user_id}
+
+# Tier-protected endpoint (PROFESSIONAL or higher)
+@app.get("/api/analytics")
+async def get_analytics(auth: AuthContext = Depends(require_professional)):
+    return {"analytics": "professional data"}
+
+# Tier and active subscription required
+@app.get("/api/premium/reports")
+async def get_premium_reports(
+    auth: AuthContext = Depends(require_tier_and_active(SubscriptionTier.BASIC))
+):
+    return {"reports": "premium data"}
+
+# Custom tier check within endpoint
+@app.get("/api/features")
+async def get_features(user: UserContext = Depends(get_current_user)):
+    features = ["basic_dashboard"]
+
+    if user.has_minimum_tier(SubscriptionTier.PROFESSIONAL):
+        features.append("advanced_analytics")
+
+    if user.has_minimum_tier(SubscriptionTier.ENTERPRISE):
+        features.append("custom_integrations")
+
+    return {"features": features, "tier": user.subscription_tier.value}
 ```
 
 ## License

{auth_gate-0.2.3 → auth_gate-0.3.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "auth-gate"
-version = "0.2.3"
-description = "Enterprise-grade authentication for microservices with Kong and Keycloak integration"
+version = "0.3.0"
+description = "Enterprise-grade authentication for microservices with Kong/Keycloak integration and subscription tier support"
 readme = "README.md"
 requires-python = ">=3.11"
 license = {text = "MIT"}