abs-auth-rbac-core 0.2.1__tar.gz → 0.2.3__tar.gz

{abs_auth_rbac_core-0.2.1 → abs_auth_rbac_core-0.2.3}/PKG-INFO

@@ -1,15 +1,16 @@
 Metadata-Version: 2.3
 Name: abs-auth-rbac-core
-Version: 0.2.1
+Version: 0.2.3
 Summary: RBAC and Auth core utilities including JWT token management.
 License: MIT
 Author: AutoBridgeSystems
 Author-email: info@autobridgesystems.com
-Requires-Python: >=3.13,<4.0
+Requires-Python: >=3.12,<4.0
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: abs-exception-core (>=0.1.0,<0.2.0)
+Requires-Dist: abs-exception-core (>=0.1.4,<0.2.0)
 Requires-Dist: casbin (>=1.41.0,<2.0.0)
 Requires-Dist: casbin-redis-watcher (>=1.3.0,<2.0.0)
 Requires-Dist: casbin-sqlalchemy-adapter (>=1.4.0,<2.0.0)
@@ -24,30 +25,55 @@ Description-Content-Type: text/markdown
 
 A comprehensive authentication and Role-Based Access Control (RBAC) package for FastAPI applications. This package provides robust JWT-based authentication and flexible role-based permission management using Casbin with Redis support for real-time policy updates.
 
-## Features
+## 🚀 Features
 
-- **JWT-based Authentication**: Secure token-based authentication with customizable expiration
-- **Password Hashing**: Secure password storage using bcrypt
-- **Role-Based Access Control (RBAC)**: Flexible permission management using Casbin
-- **Real-time Policy Updates**: Redis integration for live policy synchronization
-- **User-Role Management**: Dynamic role assignment and revocation
-- **Permission Enforcement**: Decorator-based permission checking
-- **Middleware Integration**: Seamless FastAPI middleware integration
-- **Comprehensive Error Handling**: Built-in exception handling for security scenarios
+- **🔐 JWT-based Authentication**: Secure token-based authentication with customizable expiration
+- **🔒 Password Security**: Secure password storage using bcrypt with passlib
+- **👥 Role-Based Access Control (RBAC)**: Flexible permission management using Casbin
+- **⚡ Real-time Policy Updates**: Redis integration for live policy synchronization
+- **🔄 User-Role Management**: Dynamic role assignment and revocation
+- **🛡️ Permission Enforcement**: Decorator-based permission checking
+- **🔌 Middleware Integration**: Seamless FastAPI middleware integration
+- **📝 Comprehensive Error Handling**: Built-in exception handling for security scenarios
+- **🏗️ Dependency Injection Ready**: Compatible with dependency-injector
+- **📊 Permission Constants**: Predefined permission constants and enums
 
-## Installation
+## 📦 Installation
 
 ```bash
 pip install abs-auth-rbac-core
 ```
 
-## Quick Start
+## 🏗️ Architecture Overview
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   FastAPI App   │    │   Auth Middleware│    │   RBAC Service  │
+│                 │    │                 │    │                 │
+│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
+│ │   Routes    │ │◄──►│ │JWT Validation│ │◄──►│ │Permission   │ │
+│ │             │ │    │ │User Fetch   │ │    │ │Checking     │ │
+│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+         │                       │                       │
+         │                       │                       │
+         ▼                       ▼                       ▼
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Database      │    │   Redis         │    │   Casbin        │
+│   (Users,       │    │   (Policy       │    │   (Policy       │
+│    Roles,       │    │    Updates)     │    │    Engine)      │
+│    Permissions) │    │                 │    │                 │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+## 🚀 Quick Start
 
 ### 1. Basic Setup
 
 ```python
 from abs_auth_rbac_core.auth.jwt_functions import JWTFunctions
 from abs_auth_rbac_core.rbac import RBACService
+from abs_auth_rbac_core.schema.permission import RedisWatcherSchema
 import os
 
 # Initialize JWT functions
@@ -72,14 +98,13 @@ rbac_service = RBACService(
 
 ### 2. Authentication Setup
 
-The auth middleware can be implemented in two ways:
-
-#### Option 1: Using the Package Middleware (Recommended)
-
-The package middleware automatically handles JWT token validation and sets the user in the request state:
+#### Option 1: Using Package Middleware (Recommended)
 
 ```python
 from abs_auth_rbac_core.auth.middleware import auth_middleware
+from fastapi import FastAPI, Depends
+
+app = FastAPI()
 
 # Create authentication middleware
 auth_middleware = auth_middleware(
@@ -88,7 +113,7 @@ auth_middleware = auth_middleware(
     jwt_algorithm=os.getenv("JWT_ALGORITHM", "HS256")
 )
 
-# Apply to specific routers (recommended approach)
+# Apply to specific routers
 app.include_router(
     protected_router,
     dependencies=[Depends(auth_middleware)]
@@ -99,17 +124,16 @@ app.include_router(public_router)
 ```
 
 **How it works:**
-1. The middleware validates the JWT token from the Authorization header
-2. Extracts the user UUID from the token payload
-3. Fetches the user from the database using the UUID
-4. **Sets the user object in `request.state.user`**
-5. Returns the user object for use in route handlers
+1. ✅ Validates JWT token from Authorization header
+2. ✅ Extracts user UUID from token payload
+3. ✅ Fetches user from database using UUID
+4. ✅ Sets user object in `request.state.user`
+5. ✅ Returns user object for route handlers
 
 **Accessing the user in routes:**
 ```python
 @router.get("/profile")
 async def get_profile(request: Request):
-    # User is automatically available in request.state.user
     user = request.state.user
     return {"user_id": user.uuid, "email": user.email}
 ```
@@ -117,12 +141,11 @@ async def get_profile(request: Request):
 #### Option 2: Custom Authentication Function
 
 ```python
-from abs_auth_rbac_core.auth import JWTFunctions
+from abs_auth_rbac_core.auth.jwt_functions import JWTFunctions
 from fastapi import Security, HTTPAuthorizationCredentials
 from fastapi.security import HTTPBearer
 from abs_exception_core.exceptions import UnauthorizedError
 
-# Create security scheme
 security = HTTPBearer(auto_error=False)
 jwt_functions = JWTFunctions(
     secret_key=os.getenv("JWT_SECRET_KEY"),
@@ -138,7 +161,6 @@ async def get_current_user(
             raise UnauthorizedError(detail="No authorization token provided")
 
         token = credentials.credentials
-        # Remove 'Bearer ' prefix if present
         if token.lower().startswith("bearer "):
             token = token[7:]
 
@@ -150,7 +172,6 @@ async def get_current_user(
     except Exception as e:
         raise UnauthorizedError(detail=str(e))
 
-# Use in individual routes
 @app.get("/protected")
 async def protected_route(current_user: dict = Depends(get_current_user)):
     return {"message": f"Hello {current_user.get('name')}"}
@@ -180,35 +201,41 @@ has_permission = rbac_service.check_permission(
     module="USER_MANAGEMENT"
 )
 
-# Get user permissions
+# Get user permissions and roles
 user_permissions = rbac_service.get_user_permissions(user_uuid="user_uuid")
 user_roles = rbac_service.get_user_roles(user_uuid="user_uuid")
 ```
 
-## Core Components
+## 🏛️ Core Components
 
 ### Authentication (`auth/`)
-- `jwt_functions.py`: JWT token management and password hashing
-- `middleware.py`: Authentication middleware for FastAPI
-- `auth_functions.py`: Core authentication functions
+- **`jwt_functions.py`**: JWT token management and password hashing
+- **`middleware.py`**: Authentication middleware for FastAPI
+- **`auth_functions.py`**: Core authentication functions
 
 ### RBAC (`rbac/`)
-- `service.py`: Main RBAC service with role and permission management
-- `decorator.py`: Decorators for permission checking
+- **`service.py`**: Main RBAC service with role and permission management
+- **`decorator.py`**: Decorators for permission checking
+- **`policy.conf`**: Casbin policy configuration
 
 ### Models (`models/`)
-- `user.py`: User model
-- `roles.py`: Role model
-- `permissions.py`: Permission model
-- `user_role.py`: User-Role association model
-- `role_permission.py`: Role-Permission association model
-- `rbac_model.py`: Base RBAC model
-- `base_model.py`: Base model with common fields
+- **`user.py`**: User model
+- **`roles.py`**: Role model
+- **`permissions.py`**: Permission model
+- **`user_role.py`**: User-Role association model
+- **`role_permission.py`**: Role-Permission association model
+- **`user_permission.py`**: User-Permission association model
+- **`rbac_model.py`**: Base RBAC model
+- **`base_model.py`**: Base model with common fields
+- **`gov_casbin_rule.py`**: Casbin rule model
+
+### Schema (`schema/`)
+- **`permission.py`**: Permission-related schemas
 
 ### Utilities (`util/`)
-- `permission_constants.py`: Predefined permission constants and enums
+- **`permission_constants.py`**: Predefined permission constants and enums
 
-## Complete Implementation Example
+## 🔧 Complete Implementation Example
 
 ### 1. Dependency Injection Setup
 
@@ -216,6 +243,7 @@ user_roles = rbac_service.get_user_roles(user_uuid="user_uuid")
 from dependency_injector import containers, providers
 from abs_auth_rbac_core.auth.middleware import auth_middleware
 from abs_auth_rbac_core.rbac import RBACService
+from abs_auth_rbac_core.schema.permission import RedisWatcherSchema
 from abs_auth_rbac_core.util.permission_constants import (
     PermissionAction,
     PermissionModule,
@@ -230,7 +258,6 @@ class Container(containers.DeclarativeContainer):
             "src.api.endpoints.rbac.permission_route",
             "src.api.endpoints.rbac.role_route",
             "src.api.endpoints.rbac.users_route",
-            # Add other modules that need dependency injection
         ]
     )
     
@@ -263,25 +290,24 @@ container = Container()
 app.container = container
 ```
 
-### 2. Complete Application Setup
+### 2. Application Setup
 
 ```python
 from fastapi import FastAPI, Depends
+from fastapi.middleware.cors import CORSMiddleware
 from dependency_injector.wiring import Provide, inject
 from src.core.container import Container
 
-@singleton
 class CreateApp:
     def __init__(self):
         self.container = Container()
         self.db = self.container.db()
-        # Get the auth middleware factory
         self.auth_middleware = self.container.get_auth_middleware()
 
         self.app = FastAPI(
             title="Your Service",
             description="Service Description", 
-            version="0.0.1"
+            version="0.2.0"
         )
         
         # Apply CORS middleware
@@ -326,11 +352,8 @@ from abs_auth_rbac_core.util.permission_constants import (
 # Protected router (requires authentication)
 router = APIRouter(prefix="/users")
 
-# Public router (no authentication required)
-public_router = APIRouter(prefix="/users")
-
-# Public route example (no authentication or permissions required)
-@public_router.post("/all", response_model=FindUserResult)
+# Public route example
+@router.post("/all", response_model=FindUserResult)
 @inject
 async def get_user_list(
     request: Request,
@@ -359,197 +382,7 @@ async def get_user(
     return service.get_user_profile("id", user_id, rbac_service)
 ```
 
-**How the RBAC decorator works:**
-1. The `@rbac_require_permission` decorator automatically extracts the user from `request.state.user`
-2. Gets the user's UUID: `current_user_uuid = request.state.user.uuid`
-3. Checks if the user has the required permissions using the RBAC service
-4. If permission is denied, raises `PermissionDeniedError`
-5. If permission is granted, the route handler executes normally
-
-**Important:** The `request: Request` parameter is required in routes that use the `@rbac_require_permission` decorator because it needs access to `request.state.user`.
-
-### Authentication Flow Overview
-
-```
-1. Client sends request with Authorization header
-   Authorization: Bearer <jwt_token>
-
-2. Auth middleware intercepts the request
-   ├── Validates JWT token
-   ├── Extracts user UUID from token
-   ├── Fetches user from database
-   └── Sets user in request.state.user
-
-3. RBAC decorator checks permissions
-   ├── Gets user UUID from request.state.user
-   ├── Checks permissions against Casbin policies
-   └── Allows/denies access based on permissions
-
-4. Route handler executes (if permissions granted)
-   └── Can access user via request.state.user
-```
-
-### Accessing Current User
-
-#### In Routes with RBAC Decorator
-```python
-@router.get("/my-profile")
-@inject
-@rbac_require_permission(
-    f"{PermissionModule.USER_MANAGEMENT.value}:{PermissionResource.USER_MANAGEMENT.value}:{PermissionAction.VIEW.value}"
-)
-async def get_my_profile(
-    request: Request,
-    rbac_service: RBACService = Depends(Provide[Container.rbac_service]),
-):
-    # Access current user from request state
-    current_user = request.state.user
-    return service.get_user_profile("uuid", current_user.uuid, rbac_service)
-```
-
-#### In Routes with Custom Auth Function
-```python
-@router.get("/profile")
-async def get_profile(current_user: dict = Depends(get_current_user)):
-    # current_user is the decoded JWT payload
-    return {"user_id": current_user["uuid"], "email": current_user["email"]}
-```
-
-#### In Service Methods
-```python
-def some_service_method(self, user_uuid: str, rbac_service: RBACService):
-    # Get user permissions
-    permissions = rbac_service.get_user_permissions(user_uuid=user_uuid)
-    # Get user roles
-    roles = rbac_service.get_user_roles(user_uuid=user_uuid)
-    return {"permissions": permissions, "roles": roles}
-```
-
-@router.post("/create")
-@inject
-@rbac_require_permission(
-    f"{PermissionModule.USER_MANAGEMENT.value}:{PermissionResource.USER_MANAGEMENT.value}:{PermissionAction.CREATE.value}"
-)
-async def create_user(
-    user: CreateUserWithRoles,
-    request: Request,
-    rbac_service: RBACService = Depends(Provide[Container.rbac_service]),
-):
-    """Create a new user with roles"""
-    new_user = service.add_user(user)
-    
-    # Assign roles if provided
-    if user.role_uuids and len(user.role_uuids) > 0 and new_user.uuid:
-        rbac_service.bulk_assign_roles_to_user(
-            user_uuid=new_user.uuid,
-            role_uuids=user.role_uuids,
-        )
-    return new_user
-
-@router.patch("/{user_id}")
-@inject
-@rbac_require_permission(
-    f"{PermissionModule.USER_MANAGEMENT.value}:{PermissionResource.USER_MANAGEMENT.value}:{PermissionAction.EDIT.value}"
-)
-async def update_user(
-    user_id: int,
-    user: UpdateUserWithRoles,
-    request: Request,
-    rbac_service: RBACService = Depends(Provide[Container.rbac_service]),
-):
-    """Update user with new attributes and roles"""
-    return service.patch_user(user_id, user, rbac_service)
-
-@router.delete("/{user_id}")
-@inject
-@rbac_require_permission(
-    f"{PermissionModule.USER_MANAGEMENT.value}:{PermissionResource.USER_MANAGEMENT.value}:{PermissionAction.DELETE.value}"
-)
-async def delete_user(
-    user_id: int,
-    request: Request,
-    rbac_service: RBACService = Depends(Provide[Container.rbac_service]),
-):
-    """Delete user"""
-    return service.remove_user(user_id, rbac_service)
-```
-
-### 3. Role and Permission Management
-
-```python
-@router.get("/roles")
-@inject
-@rbac_require_permission(
-    f"{PermissionModule.USER_MANAGEMENT.value}:{PermissionResource.ROLE_MANAGEMENT.value}:{PermissionAction.VIEW.value}"
-)
-async def get_roles(
-    request: Request,
-    rbac_service: RBACService = Depends(Provide[Container.rbac_service]),
-):
-    """Get all roles"""
-    return rbac_service.list_roles()
-
-@router.post("/roles")
-@inject
-@rbac_require_permission(
-    f"{PermissionModule.USER_MANAGEMENT.value}:{PermissionResource.ROLE_MANAGEMENT.value}:{PermissionAction.CREATE.value}"
-)
-async def create_role(
-    role: CreateRoleSchema,
-    request: Request,
-    rbac_service: RBACService = Depends(Provide[Container.rbac_service]),
-):
-    """Create a new role with permissions"""
-    return rbac_service.create_role(
-        name=role.name,
-        description=role.description,
-        permission_ids=role.permission_ids
-    )
-
-@router.get("/user-permissions/{user_uuid}")
-@inject
-@rbac_require_permission([
-    f"{PermissionModule.USER_MANAGEMENT.value}:{PermissionResource.USER_MANAGEMENT.value}:{PermissionAction.VIEW.value}",
-    f"{PermissionModule.USER_MANAGEMENT.value}:{PermissionResource.ROLE_MANAGEMENT.value}:{PermissionAction.VIEW.value}"
-])
-async def get_user_permissions(
-    user_uuid: str,
-    request: Request,
-    rbac_service: RBACService = Depends(Provide[Container.rbac_service]),
-):
-    """Get all permissions for a user"""
-    return rbac_service.get_user_permissions(user_uuid)
-```
-
-### 4. User Profile with Permissions
-
-```python
-def get_user_profile(self, attr: str, value: any, rbac_service: RBACService) -> UserProfile:
-    """Get user profile with permissions and roles"""
-    user = self.user_repository.read_by_attr(attr, value, eager=True)
-    
-    # Get user permissions and roles
-    permissions = rbac_service.get_user_permissions(user_uuid=user.uuid)
-    user_permissions = rbac_service.get_user_only_permissions(user_uuid=user.uuid)
-    roles = rbac_service.get_user_roles(user_uuid=user.uuid)
-    
-    # Convert roles to response models
-    role_models = [UserRoleResponse.model_validate(role) for role in roles]
-    
-    return UserProfile(
-        id=user.id,
-        uuid=user.uuid,
-        email=user.email,
-        name=user.name,
-        is_active=user.is_active,
-        last_login_at=user.last_login_at,
-        permissions=permissions,
-        user_permissions=user_permissions,
-        roles=role_models,
-    )
-```
-
-## Permission System
+## 🔐 Permission System
 
 ### Permission Format
 Permissions follow the format: `module:resource:action`
@@ -588,13 +421,13 @@ async def get_user_with_roles():
     pass
 ```
 
-## Configuration
+## ⚙️ Configuration
 
 ### Environment Variables
 
 ```bash
 # JWT Configuration
-JWT_SECRET_KEY=your-secret-key
+JWT_SECRET_KEY=your-secret-key-here
 JWT_ALGORITHM=HS256
 JWT_ACCESS_TOKEN_EXPIRE_MINUTES=60
 JWT_REFRESH_TOKEN_EXPIRE_MINUTES=1440
@@ -620,7 +453,104 @@ The package uses a default policy configuration that supports:
 
 Policy format: `[role] [resource] [action] [module]`
 
-## Error Handling
+## 🛠️ Advanced Usage
+
+### User Profile with Permissions
+
+```python
+def get_user_profile(self, attr: str, value: any, rbac_service: RBACService) -> UserProfile:
+    """Get user profile with permissions and roles"""
+    user = self.user_repository.read_by_attr(attr, value, eager=True)
+    
+    # Get user permissions and roles
+    permissions = rbac_service.get_user_permissions(user_uuid=user.uuid)
+    user_permissions = rbac_service.get_user_only_permissions(user_uuid=user.uuid)
+    roles = rbac_service.get_user_roles(user_uuid=user.uuid)
+    
+    # Convert roles to response models
+    role_models = [UserRoleResponse.model_validate(role) for role in roles]
+    
+    return UserProfile(
+        id=user.id,
+        uuid=user.uuid,
+        email=user.email,
+        name=user.name,
+        is_active=user.is_active,
+        last_login_at=user.last_login_at,
+        permissions=permissions,
+        user_permissions=user_permissions,
+        roles=role_models,
+    )
+```
+
+### Role and Permission Management
+
+```python
+@router.get("/roles")
+@inject
+@rbac_require_permission(
+    f"{PermissionModule.USER_MANAGEMENT.value}:{PermissionResource.ROLE_MANAGEMENT.value}:{PermissionAction.VIEW.value}"
+)
+async def get_roles(
+    request: Request,
+    rbac_service: RBACService = Depends(Provide[Container.rbac_service]),
+):
+    """Get all roles"""
+    return rbac_service.list_roles()
+
+@router.post("/roles")
+@inject
+@rbac_require_permission(
+    f"{PermissionModule.USER_MANAGEMENT.value}:{PermissionResource.ROLE_MANAGEMENT.value}:{PermissionAction.CREATE.value}"
+)
+async def create_role(
+    role: CreateRoleSchema,
+    request: Request,
+    rbac_service: RBACService = Depends(Provide[Container.rbac_service]),
+):
+    """Create a new role with permissions"""
+    return rbac_service.create_role(
+        name=role.name,
+        description=role.description,
+        permission_ids=role.permission_ids
+    )
+```
+
+## 🔍 Authentication Flow
+
+```
+1. Client Request
+   ┌─────────────────┐
+   │ Authorization:  │
+   │ Bearer <token>  │
+   └─────────────────┘
+           │
+           ▼
+2. Auth Middleware
+   ┌──────────────────────┐
+   │ Validate JWT         │
+   │ Extract User ID      │
+   │ Fetch User           │
+   │ Set in Request state │
+   └──────────────────────┘
+           │
+           ▼
+3. RBAC Decorator
+   ┌─────────────────┐
+   │ Get User UUID   │
+   │ Check Permissions│
+   │ Allow/Deny      │
+   └─────────────────┘
+           │
+           ▼
+4. Route Handler
+   ┌─────────────────┐
+   │ Execute Logic   │
+   │ Return Response │
+   └─────────────────┘
+```
+
+## 🚨 Error Handling
 
 The package includes comprehensive error handling:
 
@@ -647,40 +577,7 @@ except PermissionDeniedError as e:
     return {"error": "Permission denied", "detail": str(e)}
 ```
 
-## Best Practices
-
-### 1. Security
-- Always use environment variables for sensitive data
-- Implement proper password policies
-- Regularly rotate JWT secret keys
-- Use HTTPS in production
-- Implement rate limiting for authentication endpoints
-
-### 2. Permission Design
-- Use descriptive permission names
-- Group related permissions by module
-- Implement least privilege principle
-- Document permission requirements
-
-### 3. Performance
-- Use Redis for real-time policy updates
-- Implement caching for frequently accessed permissions
-- Optimize database queries with eager loading
-- Monitor policy enforcement performance
-
-### 4. Maintenance
-- Regularly audit user permissions
-- Implement permission cleanup for inactive users
-- Monitor and log security events
-- Keep dependencies updated
-
-### 5. Testing
-- Test all permission combinations
-- Mock external dependencies
-- Test error scenarios
-- Implement integration tests
-
-## Monitoring and Logging
+## 📊 Monitoring and Logging
 
 ```python
 import logging
@@ -698,29 +595,8 @@ logger.info(f"Permission check: {user_uuid} -> {resource}:{action}:{module}")
 logger.info(f"Roles assigned to user {user_uuid}: {role_uuids}")
 ```
 
-## Migration and Deployment
-
-### Database Migrations
-Ensure your database has the required tables:
-- `users`
-- `roles`
-- `permissions`
-- `user_roles`
-- `role_permissions`
-- `gov_casbin_rules`
+## 🏥 Health Checks
 
-### Redis Setup
-For real-time policy updates, configure Redis:
-```bash
-# Install Redis
-sudo apt-get install redis-server
-
-# Configure Redis
-redis-cli config set requirepass your-password
-redis-cli config set notify-keyspace-events KEA
-```
-
-### Health Checks
 ```python
 @app.get("/health")
 async def health_check():
@@ -731,31 +607,117 @@ async def health_check():
     }
 ```
 
-## Troubleshooting
+## 🔧 Troubleshooting
 
 ### Common Issues
 
-1. **Authentication Fails**
-   - Check JWT secret key configuration
-   - Verify token expiration settings
-   - Ensure user exists in database
+| Issue | Solution |
+|-------|----------|
+| **Authentication Fails** | Check JWT secret key, token expiration, user existence |
+| **Permission Denied** | Verify user roles, role-permission assignments, permission format |
+| **Redis Connection Issues** | Check Redis server status, connection parameters, pub/sub support |
+| **Policy Not Updating** | Verify Redis watcher configuration, policy format, Redis logs |
 
-2. **Permission Denied**
-   - Verify user has required roles
-   - Check role-permission assignments
-   - Validate permission format
+### Debug Mode
 
-3. **Redis Connection Issues**
-   - Check Redis server status
-   - Verify connection parameters
-   - Ensure Redis supports pub/sub
+```python
+# Enable debug logging
+import logging
+logging.basicConfig(level=logging.DEBUG)
 
-4. **Policy Not Updating**
-   - Check Redis watcher configuration
-   - Verify policy format
-   - Monitor Redis logs
+# Check RBAC service status
+print(f"Watcher active: {rbac_service.is_watcher_active()}")
+print(f"Policy count: {rbac_service.get_policy_count()}")
+```
 
-## License
+## 📋 Dependencies
+
+### Core Dependencies
+- **pyjwt** (>=2.10.1,<3.0.0): JWT token handling
+- **fastapi[standard]** (>=0.115.12,<0.116.0): Web framework
+- **passlib** (>=1.7.4,<2.0.0): Password hashing
+- **sqlalchemy** (>=2.0.40,<3.0.0): Database ORM
+- **casbin** (>=1.41.0,<2.0.0): RBAC policy engine
+- **casbin-sqlalchemy-adapter** (>=1.4.0,<2.0.0): Database adapter
+- **casbin-redis-watcher** (>=1.3.0,<2.0.0): Real-time policy updates
+
+### Internal Dependencies
+- **abs-exception-core** (>=0.1.4,<0.2.0): Exception handling
+- **psycopg2-binary** (>=2.9.10,<3.0.0): PostgreSQL adapter
+
+## 🚀 Best Practices
+
+### Security
+- ✅ Use environment variables for sensitive data
+- ✅ Implement proper password policies
+- ✅ Regularly rotate JWT secret keys
+- ✅ Use HTTPS in production
+- ✅ Implement rate limiting for authentication endpoints
+
+### Permission Design
+- ✅ Use descriptive permission names
+- ✅ Group related permissions by module
+- ✅ Implement least privilege principle
+- ✅ Document permission requirements
+
+### Performance
+- ✅ Use Redis for real-time policy updates
+- ✅ Implement caching for frequently accessed permissions
+- ✅ Optimize database queries with eager loading
+- ✅ Monitor policy enforcement performance
+
+### Maintenance
+- ✅ Regularly audit user permissions
+- ✅ Implement permission cleanup for inactive users
+- ✅ Monitor and log security events
+- ✅ Keep dependencies updated
+
+## 📚 API Reference
+
+### RBACService Methods
+
+| Method | Description |
+|--------|-------------|
+| `create_role(name, description, permission_ids)` | Create a new role |
+| `assign_role_to_user(user_uuid, role_uuid)` | Assign role to user |
+| `bulk_assign_roles_to_user(user_uuid, role_uuids)` | Assign multiple roles |
+| `check_permission(user_uuid, resource, action, module)` | Check user permission |
+| `get_user_permissions(user_uuid)` | Get all user permissions |
+| `get_user_roles(user_uuid)` | Get user roles |
+| `list_roles()` | List all roles |
+| `is_watcher_active()` | Check Redis watcher status |
+
+### JWT Functions
+
+| Method | Description |
+|--------|-------------|
+| `create_access_token(data)` | Create JWT access token |
+| `decode_jwt(token)` | Decode and validate JWT |
+| `hash_password(password)` | Hash password with bcrypt |
+| `verify_password(password, hashed)` | Verify password hash |
+
+## 📄 License
 
 This project is licensed under the MIT License - see the LICENSE file for details.
 
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## 📞 Support
+
+For support and questions:
+- Email: info@autobridgesystems.com
+- Documentation: [Link to documentation]
+- Issues: [GitHub Issues]
+
+---
+
+**Version**: 0.2.0  
+**Last Updated**: 2024  
+**Python Version**: >=3.12,<4.0
+