identity-plan-kit 0.2.4__tar.gz → 0.2.5__tar.gz

{identity_plan_kit-0.2.4 → identity_plan_kit-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: identity-plan-kit
-Version: 0.2.4
+Version: 0.2.5
 Summary: Modern FastAPI library for authentication, RBAC, subscription plans, and usage tracking
 Author-email: harut <harut.avetisyan2002@gmail.com>
 License: MIT
@@ -73,6 +73,183 @@ Modern FastAPI library for authentication, RBAC, subscription plans, and usage t
 - **Account Lockout**: Brute-force protection
 - **CLI Tools**: Database migrations and management
 
+---
+
+## What IPK Provides vs What You Must Implement
+
+### Provided Out of the Box
+
+| Feature | Description |
+|---------|-------------|
+| **Google OAuth Authentication** | Complete OAuth 2.0 flow with CSRF protection |
+| **JWT Token Management** | Access/refresh token generation, validation, and rotation |
+| **Token Theft Detection** | Automatic account deactivation when revoked token is reused |
+| **Default Roles** | Pre-configured `admin` and `user` roles |
+| **Default Plans** | Pre-configured `free` and `pro` plans |
+| **Permission Infrastructure** | `check_permission()`, `require_permission()` methods |
+| **Atomic Quota Checking** | Race-condition safe quota consumption (TOCTOU protected) |
+| **Account Lockout** | Brute-force protection with configurable thresholds |
+| **Token Cleanup** | Automatic expired token removal |
+| **Health Checks** | Kubernetes-ready `/health/live` and `/health/ready` probes |
+| **Graceful Shutdown** | Request draining before shutdown |
+| **Database Migrations** | All tables created via `ipk db upgrade` |
+| **Prometheus Metrics** | Optional observability (requires `[metrics]` extra) |
+| **Audit Logging** | Security events logged automatically |
+| **Idempotent Token Refresh** | Duplicate refresh requests return same tokens (30s window) |
+| **Idempotent Quota Consumption** | When `idempotency_key` provided, prevents double-deduction |
+| **Rate Limiting** | Configurable per-endpoint rate limits |
+
+### You Must Implement
+
+| Responsibility | Why | Example |
+|----------------|-----|---------|
+| **Define Features** | IPK doesn't know what features your app has | `"api_calls"`, `"ai_generations"`, `"storage_gb"` |
+| **Assign Features to Plans** | Business decision about what's included | Free: 100 API calls, Pro: unlimited |
+| **Set Plan Limits** | Your pricing/quota decisions | `{"api_calls": 1000, "ai_generations": 50}` |
+| **Define Permission Codes** | App-specific access control | `"admin.users.delete"`, `"reports.export"` |
+| **Assign Permissions to Roles** | Which roles can do what | Admin gets `"admin.*"`, User gets `"feature.use"` |
+| **Payment Webhook Integration** | IPK doesn't handle payments | Call `plan_service.assign_plan()` from Stripe webhook |
+| **Webhook Deduplication** | Payment providers retry webhooks | Check `event_id` before processing (see below) |
+| **Quota Checks in Routes** | IPK doesn't auto-enforce quotas | Call `check_and_consume_quota()` in your endpoints |
+| **Authorization for Plan Ops** | IPK doesn't verify callers by default | Verify webhook signatures, check admin role |
+
+---
+
+## Critical Warnings
+
+### Production Deployments (Multi-Instance)
+
+> **Redis is REQUIRED for multi-instance deployments**
+
+Without Redis, each instance has its own:
+- OAuth state storage (login fails if callback hits different instance)
+- Rate limit counters (users bypass limits via different instances)
+- Permission cache (inconsistent permissions across instances)
+
+```bash
+# Set Redis URL for production
+IPK_REDIS_URL=redis://localhost:6379/0
+IPK_REQUIRE_REDIS=true  # Fail-fast if Redis unavailable
+```
+
+### Token Theft Protection
+
+When a refresh token is used **after being revoked**, IPK assumes token theft:
+1. ALL tokens for that user are revoked
+2. User account is **automatically deactivated**
+3. User must contact support to reactivate
+
+This is intentional security behavior, not a bug.
+
+### Webhook Idempotency (NOT Auto-Handled)
+
+**Plan management methods do NOT handle idempotency.** If your webhook provider retries requests (Stripe retries on timeout), duplicate calls will create issues.
+
+**You MUST implement deduplication:**
+
+```python
+@app.post("/webhooks/stripe")
+async def stripe_webhook(request: Request):
+    event = stripe.Webhook.construct_event(...)
+
+    # CRITICAL: Check if already processed
+    if await is_event_processed(event.id):
+        return {"status": "already_processed"}
+
+    if event.type == "checkout.session.completed":
+        await kit.plan_service.assign_plan(
+            user_id=UUID(event.data.object.client_reference_id),
+            plan_code="pro",
+        )
+
+    await mark_event_processed(event.id)
+    return {"status": "ok"}
+```
+
+### Authorization is Your Responsibility
+
+Plan management methods (`assign_plan`, `cancel_plan`, `update_plan_limits`, `reset_usage`) are **privileged operations**. IPK does NOT verify the caller is authorized.
+
+**You MUST verify authorization before calling:**
+
+```python
+# Option 1: Verify in your code before calling
+@app.post("/admin/users/{user_id}/plan")
+async def admin_assign_plan(user_id: UUID, current_user: User = Depends(CurrentUser(kit))):
+    # Verify caller is admin
+    await kit.rbac_service.require_permission(
+        current_user.id, current_user.role_id, "admin.plans.manage"
+    )
+    await kit.plan_service.assign_plan(user_id=user_id, plan_code="pro")
+
+# Option 2: Configure authorization callback
+async def check_authorization(operation: str, target_user_id: UUID, context: dict | None) -> bool:
+    if context and context.get("is_webhook"):
+        return True  # Verified webhooks are authorized
+    if context and context.get("is_admin"):
+        return True
+    return False
+
+kit = IdentityPlanKit(config, authorization_callback=check_authorization)
+```
+
+---
+
+## Integration Examples
+
+### Quota Tracking in Routes
+
+```python
+@app.post("/generate")
+async def generate(user: User = Depends(CurrentUser(kit))):
+    usage = await kit.plan_service.check_and_consume_quota(
+        user_id=user.id,
+        feature_code="ai_generations",
+        amount=1,
+        idempotency_key=request.headers.get("X-Idempotency-Key"),  # Safe retries
+    )
+
+    if not usage.has_access:
+        raise HTTPException(
+            status_code=429,
+            detail=f"Quota exceeded: {usage.used}/{usage.limit}"
+        )
+
+    # Your feature logic here
+    return {"remaining": usage.remaining}
+```
+
+### Permission Enforcement
+
+```python
+@app.delete("/admin/users/{user_id}")
+async def delete_user(user_id: UUID, current_user: User = Depends(CurrentUser(kit))):
+    await kit.rbac_service.require_permission(
+        user_id=current_user.id,
+        role_id=current_user.role_id,
+        permission_code="admin.users.delete",
+    )
+    # Delete logic here
+```
+
+### Idempotency for Quota Consumption
+
+```python
+# Generate a unique key per logical operation
+idempotency_key = f"{user.id}:{request_id}:generate_image"
+
+# First request: checks quota, consumes 1, caches result
+# Retry request: returns cached result, no double-deduction
+result = await kit.plan_service.check_and_consume_quota(
+    user_id=user.id,
+    feature_code="ai_generation",
+    amount=1,
+    idempotency_key=idempotency_key,
+)
+```
+
+---
+
 ## Installation
 
 ```bash
@@ -407,6 +584,26 @@ All configuration is via environment variables or `IdentityPlanKitConfig`:
 | `IPK_METRICS_PATH` | Path for metrics endpoint | `/metrics` |
 | `IPK_ENABLE_AUTO_CLEANUP` | Auto cleanup expired tokens | `true` |
 | `IPK_CLEANUP_INTERVAL_HOURS` | Cleanup interval in hours | `6.0` |
+| `IPK_DATABASE_STATEMENT_TIMEOUT_MS` | PostgreSQL statement timeout | `30000` |
+| `IPK_TOKEN_REFRESH_IDEMPOTENCY_TTL_SECONDS` | Token refresh idempotency window | `30` |
+| `IPK_QUOTA_IDEMPOTENCY_TTL_SECONDS` | Quota consumption idempotency window | `60` |
+| `IPK_REQUIRE_REDIS` | Fail if Redis unavailable | Auto (true in prod) |
+
+### Important Configuration Notes
+
+**Database Statement Timeout**: Long-running queries are killed after 30s by default. Adjust for migrations:
+
+```bash
+# For API servers (shorter timeout)
+IPK_DATABASE_STATEMENT_TIMEOUT_MS=10000  # 10 seconds
+
+# For migration scripts (longer timeout)
+IPK_DATABASE_STATEMENT_TIMEOUT_MS=300000  # 5 minutes
+```
+
+**Token Refresh Idempotency**: Duplicate refresh requests within 30s return the same tokens. This prevents "token revoked" errors when clients retry due to network issues.
+
+**Quota Idempotency**: When `idempotency_key` is provided to `check_and_consume_quota()`, duplicate requests within 60s return cached results without double-deducting.
 
 ## Prometheus Metrics (Optional)
 

{identity_plan_kit-0.2.4 → identity_plan_kit-0.2.5}/README.md

@@ -13,6 +13,183 @@ Modern FastAPI library for authentication, RBAC, subscription plans, and usage t
 - **Account Lockout**: Brute-force protection
 - **CLI Tools**: Database migrations and management
 
+---
+
+## What IPK Provides vs What You Must Implement
+
+### Provided Out of the Box
+
+| Feature | Description |
+|---------|-------------|
+| **Google OAuth Authentication** | Complete OAuth 2.0 flow with CSRF protection |
+| **JWT Token Management** | Access/refresh token generation, validation, and rotation |
+| **Token Theft Detection** | Automatic account deactivation when revoked token is reused |
+| **Default Roles** | Pre-configured `admin` and `user` roles |
+| **Default Plans** | Pre-configured `free` and `pro` plans |
+| **Permission Infrastructure** | `check_permission()`, `require_permission()` methods |
+| **Atomic Quota Checking** | Race-condition safe quota consumption (TOCTOU protected) |
+| **Account Lockout** | Brute-force protection with configurable thresholds |
+| **Token Cleanup** | Automatic expired token removal |
+| **Health Checks** | Kubernetes-ready `/health/live` and `/health/ready` probes |
+| **Graceful Shutdown** | Request draining before shutdown |
+| **Database Migrations** | All tables created via `ipk db upgrade` |
+| **Prometheus Metrics** | Optional observability (requires `[metrics]` extra) |
+| **Audit Logging** | Security events logged automatically |
+| **Idempotent Token Refresh** | Duplicate refresh requests return same tokens (30s window) |
+| **Idempotent Quota Consumption** | When `idempotency_key` provided, prevents double-deduction |
+| **Rate Limiting** | Configurable per-endpoint rate limits |
+
+### You Must Implement
+
+| Responsibility | Why | Example |
+|----------------|-----|---------|
+| **Define Features** | IPK doesn't know what features your app has | `"api_calls"`, `"ai_generations"`, `"storage_gb"` |
+| **Assign Features to Plans** | Business decision about what's included | Free: 100 API calls, Pro: unlimited |
+| **Set Plan Limits** | Your pricing/quota decisions | `{"api_calls": 1000, "ai_generations": 50}` |
+| **Define Permission Codes** | App-specific access control | `"admin.users.delete"`, `"reports.export"` |
+| **Assign Permissions to Roles** | Which roles can do what | Admin gets `"admin.*"`, User gets `"feature.use"` |
+| **Payment Webhook Integration** | IPK doesn't handle payments | Call `plan_service.assign_plan()` from Stripe webhook |
+| **Webhook Deduplication** | Payment providers retry webhooks | Check `event_id` before processing (see below) |
+| **Quota Checks in Routes** | IPK doesn't auto-enforce quotas | Call `check_and_consume_quota()` in your endpoints |
+| **Authorization for Plan Ops** | IPK doesn't verify callers by default | Verify webhook signatures, check admin role |
+
+---
+
+## Critical Warnings
+
+### Production Deployments (Multi-Instance)
+
+> **Redis is REQUIRED for multi-instance deployments**
+
+Without Redis, each instance has its own:
+- OAuth state storage (login fails if callback hits different instance)
+- Rate limit counters (users bypass limits via different instances)
+- Permission cache (inconsistent permissions across instances)
+
+```bash
+# Set Redis URL for production
+IPK_REDIS_URL=redis://localhost:6379/0
+IPK_REQUIRE_REDIS=true  # Fail-fast if Redis unavailable
+```
+
+### Token Theft Protection
+
+When a refresh token is used **after being revoked**, IPK assumes token theft:
+1. ALL tokens for that user are revoked
+2. User account is **automatically deactivated**
+3. User must contact support to reactivate
+
+This is intentional security behavior, not a bug.
+
+### Webhook Idempotency (NOT Auto-Handled)
+
+**Plan management methods do NOT handle idempotency.** If your webhook provider retries requests (Stripe retries on timeout), duplicate calls will create issues.
+
+**You MUST implement deduplication:**
+
+```python
+@app.post("/webhooks/stripe")
+async def stripe_webhook(request: Request):
+    event = stripe.Webhook.construct_event(...)
+
+    # CRITICAL: Check if already processed
+    if await is_event_processed(event.id):
+        return {"status": "already_processed"}
+
+    if event.type == "checkout.session.completed":
+        await kit.plan_service.assign_plan(
+            user_id=UUID(event.data.object.client_reference_id),
+            plan_code="pro",
+        )
+
+    await mark_event_processed(event.id)
+    return {"status": "ok"}
+```
+
+### Authorization is Your Responsibility
+
+Plan management methods (`assign_plan`, `cancel_plan`, `update_plan_limits`, `reset_usage`) are **privileged operations**. IPK does NOT verify the caller is authorized.
+
+**You MUST verify authorization before calling:**
+
+```python
+# Option 1: Verify in your code before calling
+@app.post("/admin/users/{user_id}/plan")
+async def admin_assign_plan(user_id: UUID, current_user: User = Depends(CurrentUser(kit))):
+    # Verify caller is admin
+    await kit.rbac_service.require_permission(
+        current_user.id, current_user.role_id, "admin.plans.manage"
+    )
+    await kit.plan_service.assign_plan(user_id=user_id, plan_code="pro")
+
+# Option 2: Configure authorization callback
+async def check_authorization(operation: str, target_user_id: UUID, context: dict | None) -> bool:
+    if context and context.get("is_webhook"):
+        return True  # Verified webhooks are authorized
+    if context and context.get("is_admin"):
+        return True
+    return False
+
+kit = IdentityPlanKit(config, authorization_callback=check_authorization)
+```
+
+---
+
+## Integration Examples
+
+### Quota Tracking in Routes
+
+```python
+@app.post("/generate")
+async def generate(user: User = Depends(CurrentUser(kit))):
+    usage = await kit.plan_service.check_and_consume_quota(
+        user_id=user.id,
+        feature_code="ai_generations",
+        amount=1,
+        idempotency_key=request.headers.get("X-Idempotency-Key"),  # Safe retries
+    )
+
+    if not usage.has_access:
+        raise HTTPException(
+            status_code=429,
+            detail=f"Quota exceeded: {usage.used}/{usage.limit}"
+        )
+
+    # Your feature logic here
+    return {"remaining": usage.remaining}
+```
+
+### Permission Enforcement
+
+```python
+@app.delete("/admin/users/{user_id}")
+async def delete_user(user_id: UUID, current_user: User = Depends(CurrentUser(kit))):
+    await kit.rbac_service.require_permission(
+        user_id=current_user.id,
+        role_id=current_user.role_id,
+        permission_code="admin.users.delete",
+    )
+    # Delete logic here
+```
+
+### Idempotency for Quota Consumption
+
+```python
+# Generate a unique key per logical operation
+idempotency_key = f"{user.id}:{request_id}:generate_image"
+
+# First request: checks quota, consumes 1, caches result
+# Retry request: returns cached result, no double-deduction
+result = await kit.plan_service.check_and_consume_quota(
+    user_id=user.id,
+    feature_code="ai_generation",
+    amount=1,
+    idempotency_key=idempotency_key,
+)
+```
+
+---
+
 ## Installation
 
 ```bash
@@ -347,6 +524,26 @@ All configuration is via environment variables or `IdentityPlanKitConfig`:
 | `IPK_METRICS_PATH` | Path for metrics endpoint | `/metrics` |
 | `IPK_ENABLE_AUTO_CLEANUP` | Auto cleanup expired tokens | `true` |
 | `IPK_CLEANUP_INTERVAL_HOURS` | Cleanup interval in hours | `6.0` |
+| `IPK_DATABASE_STATEMENT_TIMEOUT_MS` | PostgreSQL statement timeout | `30000` |
+| `IPK_TOKEN_REFRESH_IDEMPOTENCY_TTL_SECONDS` | Token refresh idempotency window | `30` |
+| `IPK_QUOTA_IDEMPOTENCY_TTL_SECONDS` | Quota consumption idempotency window | `60` |
+| `IPK_REQUIRE_REDIS` | Fail if Redis unavailable | Auto (true in prod) |
+
+### Important Configuration Notes
+
+**Database Statement Timeout**: Long-running queries are killed after 30s by default. Adjust for migrations:
+
+```bash
+# For API servers (shorter timeout)
+IPK_DATABASE_STATEMENT_TIMEOUT_MS=10000  # 10 seconds
+
+# For migration scripts (longer timeout)
+IPK_DATABASE_STATEMENT_TIMEOUT_MS=300000  # 5 minutes
+```
+
+**Token Refresh Idempotency**: Duplicate refresh requests within 30s return the same tokens. This prevents "token revoked" errors when clients retry due to network issues.
+
+**Quota Idempotency**: When `idempotency_key` is provided to `check_and_consume_quota()`, duplicate requests within 60s return cached results without double-deducting.
 
 ## Prometheus Metrics (Optional)
 

{identity_plan_kit-0.2.4 → identity_plan_kit-0.2.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "identity-plan-kit"
-version = "0.2.4"
+version = "0.2.5"
 description = "Modern FastAPI library for authentication, RBAC, subscription plans, and usage tracking"
 readme = "README.md"
 authors = [
@@ -140,7 +140,7 @@ testpaths = ["tests"]
 addopts = "-v --tb=short"
 
 [tool.bumpversion]
-current_version = "0.2.4"
+current_version = "0.2.5"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 tag = true

{identity_plan_kit-0.2.4 → identity_plan_kit-0.2.5}/src/identity_plan_kit/auth/handlers/oauth_routes.py

@@ -294,7 +294,8 @@ def create_auth_router(config: IdentityPlanKitConfig) -> APIRouter:  # noqa: PLR
         summary="Get current user",
         description="Get information about the authenticated user",
     )
-    async def get_me(user: CurrentUser) -> ResponseModel[UserResponse]:
+    @rate_limiter.limit(config.rate_limit_profile)
+    async def get_me(request: Request, user: CurrentUser) -> ResponseModel[UserResponse]:
         """Get current authenticated user."""
         return ResponseModel.ok(
             data=UserResponse(
@@ -313,6 +314,7 @@ def create_auth_router(config: IdentityPlanKitConfig) -> APIRouter:  # noqa: PLR
         summary="Get user profile",
         description="Get complete user profile including role, permissions, and current plan",
     )
+    @rate_limiter.limit(config.rate_limit_profile)
     async def get_profile(request: Request, user: CurrentUser) -> ResponseModel[ProfileResponse]:
         """Get complete user profile with permissions and plan."""
         kit = request.app.state.identity_plan_kit

{identity_plan_kit-0.2.4 → identity_plan_kit-0.2.5}/src/identity_plan_kit/auth/repositories/token_repo.py

@@ -146,6 +146,9 @@ class RefreshTokenRepository:
         Uses batch deletion to prevent long-running transactions and
         table-level locks on large datasets.
 
+        Uses FOR UPDATE SKIP LOCKED to allow concurrent cleanup operations
+        to process different batches of tokens without conflicts.
+
         Should be run periodically via background job.
 
         Args:
@@ -157,7 +160,8 @@ class RefreshTokenRepository:
         # Import here - delete is only needed for cleanup operations
         from sqlalchemy import delete  # noqa: PLC0415
 
-        # First, get IDs to delete (with limit)
+        # Select IDs to delete with SKIP LOCKED to allow concurrent cleanup
+        # Each concurrent call will get a different batch of rows
         select_stmt = (
             select(RefreshTokenModel.id)
             .where(
@@ -165,6 +169,7 @@ class RefreshTokenRepository:
                 | (RefreshTokenModel.revoked_at.is_not(None))
             )
             .limit(batch_size)
+            .with_for_update(skip_locked=True)
         )
         result = await self._session.execute(select_stmt)
         ids_to_delete = [row[0] for row in result.fetchall()]
@@ -172,12 +177,13 @@ class RefreshTokenRepository:
         if not ids_to_delete:
             return 0
 
-        # Delete by IDs
+        # Delete by IDs and get actual count
         delete_stmt = delete(RefreshTokenModel).where(RefreshTokenModel.id.in_(ids_to_delete))
-        await self._session.execute(delete_stmt)
+        delete_result = await self._session.execute(delete_stmt)
         await self._session.flush()
 
-        count = len(ids_to_delete)
+        # Use rowcount from DELETE to get actual deleted count
+        count = delete_result.rowcount
         logger.info(
             "refresh_tokens_cleaned",
             count=count,

{identity_plan_kit-0.2.4 → identity_plan_kit-0.2.5}/src/identity_plan_kit/auth/repositories/user_repo.py

@@ -22,12 +22,18 @@ class UserRepository:
     def __init__(self, session: AsyncSession) -> None:
         self._session = session
 
-    async def get_by_id(self, user_id: UUID) -> User | None:
+    async def get_by_id(
+        self,
+        user_id: UUID,
+        for_update: bool = False,
+    ) -> User | None:
         """
         Get user by ID.
 
         Args:
             user_id: User UUID
+            for_update: If True, lock the row for update (prevents race conditions
+                in operations that depend on current user state like is_active)
 
         Returns:
             User entity or None if not found
@@ -35,6 +41,10 @@ class UserRepository:
         stmt = (
             select(UserModel).options(selectinload(UserModel.role)).where(UserModel.id == user_id)
         )
+
+        if for_update:
+            stmt = stmt.with_for_update()
+
         result = await self._session.execute(stmt)
         model = result.scalar_one_or_none()
 

{identity_plan_kit-0.2.4 → identity_plan_kit-0.2.5}/src/identity_plan_kit/auth/services/auth_service.py

@@ -37,6 +37,8 @@ from identity_plan_kit.shared.security import (
     create_access_token,
     create_refresh_token,
     decode_token,
+    decrypt_from_cache,
+    encrypt_for_cache,
     hash_password,
     hash_token,
     verify_password,
@@ -347,17 +349,28 @@ class AuthService:
 
                 # Return the EXACT same tokens that were generated on first request
                 # This ensures true idempotency - client gets identical response
-                cached_access = cached_data.get("access_token")
-                cached_refresh = cached_data.get("refresh_token")
+                # SECURITY: Tokens are encrypted in cache - decrypt them
+                encrypted_access = cached_data.get("access_token_enc")
+                encrypted_refresh = cached_data.get("refresh_token_enc")
 
-                if cached_access and cached_refresh:
-                    return user, cached_access, cached_refresh
+                if encrypted_access and encrypted_refresh:
+                    cached_access = decrypt_from_cache(encrypted_access, self._secret_key)
+                    cached_refresh = decrypt_from_cache(encrypted_refresh, self._secret_key)
 
-                # Fallback: cache entry malformed, proceed with normal flow
-                logger.warning(
-                    "token_refresh_idempotency_cache_malformed",
-                    user_id=str(user.id),
-                )
+                    if cached_access and cached_refresh:
+                        return user, cached_access, cached_refresh
+
+                    # Decryption failed - possible key rotation or tampering
+                    logger.warning(
+                        "token_refresh_idempotency_decryption_failed",
+                        user_id=str(user.id),
+                    )
+                else:
+                    # Fallback: cache entry malformed, proceed with normal flow
+                    logger.warning(
+                        "token_refresh_idempotency_cache_malformed",
+                        user_id=str(user.id),
+                    )
 
         async with self._create_uow() as uow:
             # Find token by hash with row lock (prevents race condition)
@@ -405,7 +418,8 @@ class AuthService:
 
                 # P1 SECURITY FIX: Deactivate user to prevent further access
                 # User must contact support to reactivate
-                user = await uow.users.get_by_id(stored_token.user_id)
+                # Use FOR UPDATE to prevent race condition with concurrent requests
+                user = await uow.users.get_by_id(stored_token.user_id, for_update=True)
                 if user and user.is_active:
                     await uow.users.deactivate(
                         stored_token.user_id,
@@ -418,8 +432,11 @@ class AuthService:
 
                 raise TokenInvalidError("Token has been revoked - account secured")
 
-            # Get user
-            user = await uow.users.get_by_id(stored_token.user_id)
+            # Get user with FOR UPDATE lock to prevent race condition
+            # where user is deactivated between this check and token creation
+            # Without this, a deactivated user could get new tokens if the
+            # deactivation happens after this read but before the commit
+            user = await uow.users.get_by_id(stored_token.user_id, for_update=True)
             if user is None:
                 raise UserNotFoundError()
 
@@ -452,14 +469,15 @@ class AuthService:
 
             # Cache the actual tokens for idempotency
             # This ensures retries get the EXACT same tokens (true idempotency)
-            # Security note: Short TTL limits exposure window, and tokens
-            # are already transmitted over network. State store should be secured.
+            # SECURITY: Encrypt tokens before storing in cache to prevent
+            # exposure if cache (Redis) is compromised. Uses Fernet encryption
+            # with key derived from secret_key.
             await state_store.set(
                 idempotency_key,
                 {
                     "user_id": str(user.id),
-                    "access_token": access_token,
-                    "refresh_token": new_refresh_token,
+                    "access_token_enc": encrypt_for_cache(access_token, self._secret_key),
+                    "refresh_token_enc": encrypt_for_cache(new_refresh_token, self._secret_key),
                 },
                 ttl_seconds=self._config.token_refresh_idempotency_ttl_seconds,
             )
@@ -610,8 +628,9 @@ class AuthService:
         self._validate_password(password)
 
         async with self._create_uow() as uow:
-            # Get user with lock to prevent race conditions
-            user = await uow.users.get_by_id(user_id)
+            # Get user with FOR UPDATE lock to prevent race conditions
+            # This ensures user isn't deactivated between this check and password set
+            user = await uow.users.get_by_id(user_id, for_update=True)
 
             if user is None:
                 raise UserNotFoundError()

{identity_plan_kit-0.2.4 → identity_plan_kit-0.2.5}/src/identity_plan_kit/config.py

@@ -326,6 +326,17 @@ class IdentityPlanKitConfig(BaseSettings):
         "Allows clients to safely retry refresh requests within this window.",
     )
 
+    # Quota consumption idempotency
+    quota_idempotency_ttl_seconds: int = Field(
+        default=60,
+        ge=0,
+        le=300,
+        description="TTL for quota consumption idempotency cache in seconds. "
+        "When an idempotency_key is provided to check_and_consume_quota(), "
+        "duplicate requests within this window return the cached result "
+        "instead of consuming quota again. Set to 0 to disable idempotency.",
+    )
+
     # Rate limiting
     rate_limit_login: str = Field(
         default="20/minute",
@@ -343,6 +354,14 @@ class IdentityPlanKitConfig(BaseSettings):
         default="10/minute",
         description="Rate limit for logout endpoint",
     )
+    rate_limit_profile: str = Field(
+        default="60/minute",
+        description="Rate limit for profile endpoints (/auth/me, /auth/profile)",
+    )
+    rate_limit_plans: str = Field(
+        default="60/minute",
+        description="Rate limit for plan endpoints (/plans)",
+    )
 
     # Proxy settings
     trust_proxy_headers: bool = Field(