# User Profile Tool Documentation
## 🎯 Overview
The **User Profile Tool** provides safe, filtered user information following OWASP security best practices. It's accessible to **all authenticated users** and returns only what they need to know about their account.
## 🔒 Security Features
### Following OWASP API3:2019 - Excessive Data Exposure Prevention
✅ **Cherry-picked fields** - Only safe data returned
✅ **No sensitive IDs** - No database IDs exposed
✅ **No timestamps** - No audit/internal fields
✅ **No raw dumps** - Structured, filtered responses
✅ **Consistent format** - Same structure every time
### What's Filtered Out
❌ Internal IDs (user_id, permission_id, etc.)
❌ Timestamps (created_at, updated_at, etc.)
❌ Audit fields (created_by, updated_by, deleted_at)
❌ Internal codes (short_code, ref_id, etc.)
❌ Sensitive data (passwords, tokens, etc.)
### What's Included
✅ User name, email, title, role
✅ Organization name and type
✅ Permissions (grouped by module)
✅ Capabilities summary
✅ Module access list
---
## 📊 Example Usage
### User Question
```
"What permissions do I have?"
"What can I do?"
"What is my role?"
"What modules can I access?"
```
### Tool Response
```json
{
"meta": {
"schema_version": "1.0.0",
"tool_name": "get_user_profile",
"trace_id": "abc-123",
"generated_at": "2025-11-24T01:00:00Z",
"source": "updation_mcp",
"execution_time_ms": 5
},
"data": {
"profile": {
"name": "Sai Gundeti",
"email": "sai@updation.com",
"title": "Global Admin",
"role": "Global Admin",
"status": "Active"
},
"organization": {
"name": "Apex Motors Corporation",
"type": "Multiple"
},
"access": {
"total_permissions": 48,
"modules": [
"Approval",
"Contracts",
"Data",
"Invoice",
"Organization",
"User"
],
"permissions_by_module": {
"User": [
"View Users",
"View Details Users",
"Create Users",
"Edit Users",
"Delete Users",
"Set Filters Users",
"Manage Global Filters Users"
],
"Organization": [
"View Organizations",
"View Details Organizations",
"Create Organizations",
"Edit Organizations",
"Delete Organizations",
"View Platforms/Dealerships",
"View Details Platforms/Dealerships",
"Create Platforms/Dealerships",
"Edit Platforms/Dealerships",
"Delete Platforms/Dealerships"
],
"Contracts": [
"View Contracts",
"View Details Contracts",
"Create Contracts",
"Edit Contracts",
"Delete Contracts",
"View Dates Contracts",
"View Clauses Contracts",
"View Data Contracts",
"View Summary Contracts",
"View Files Contracts",
"View Owner Contracts",
"Manage Renewals Contracts"
],
"Data": [
"View Data",
"View Details Data",
"Create Data",
"Edit Data",
"Delete Data"
],
"Invoice": [
"View Invoices",
"View Details Invoices",
"Create Invoices",
"Edit Invoices",
"Delete Invoices",
"Mark as Paid Invoices"
],
"Approval": [
"View Approvals",
"View Details Approvals",
"Create Approvals",
"Edit Approvals",
"Delete Approvals"
]
}
},
"summary": {
"description": "Sai Gundeti is a Global Admin at Apex Motors Corporation with access to 6 modules: Approval, Contracts, Data, Invoice, Organization, User.",
"can_do": [
"Manage users and user accounts",
"Manage organizations and settings",
"View and manage vendor contracts",
"Handle invoices and payments",
"Access and manage data",
"Review and approve requests",
"Full administrative access"
]
}
},
"missing_reason": null
}
```
### AI Response to User
```
You are a Global Admin at Apex Motors Corporation with full administrative access.
You have access to 6 modules:
- User Management
- Organization Management
- Contracts
- Data
- Invoices
- Approvals
Your capabilities include:
✓ Manage users and user accounts
✓ Manage organizations and settings
✓ View and manage vendor contracts
✓ Handle invoices and payments
✓ Access and manage data
✓ Review and approve requests
✓ Full administrative access
You have 48 total permissions across these modules.
```
---
## 🔧 How It Works
### 1. Data Flow
```
User asks: "What can I do?"
↓
LLM calls: get_user_profile tool
↓
Tool gets: Cached user data (from Bearer token)
↓
Tool filters: Removes sensitive fields
↓
Tool formats: Groups permissions by module
↓
Tool returns: Structured, safe response
↓
LLM interprets: Generates user-friendly answer
```
### 2. Data Filtering
**Raw Laravel Response (48 permissions):**
```json
{
"user_permission": [
{
"id": 1,
"name": "users.index",
"guard_name": "web",
"created_at": "2024-08-27 12:53:32",
"updated_at": null,
"module_name": "User"
},
// ... 47 more
]
}
```
**Filtered Response:**
```json
{
"permissions_by_module": {
"User": [
"View Users",
"Create Users",
"Edit Users",
"Delete Users"
]
}
}
```
### 3. Permission Name Mapping
| Laravel Permission | User-Friendly Name |
|-------------------|-------------------|
| `users.index` | View Users |
| `users.create` | Create Users |
| `contract.show` | View Details Contracts |
| `invoice.paid` | Mark as Paid Invoices |
---
## 🎯 Why This Approach?
### Problem: LLM Inconsistency
**Without structured filtering:**
```
User: "What can I do?"
AI: "You have permission ID 1, 2, 3... created at 2024-08-27..."
```
**With structured filtering:**
```
User: "What can I do?"
AI: "You can manage users, view contracts, handle invoices..."
```
### Solution: Consistent Structure
1. **Filter at source** - Tool returns clean data
2. **Group logically** - Permissions by module
3. **Format clearly** - User-friendly names
4. **Summarize** - High-level capabilities
**Result:** LLM always gets same structure → Consistent answers
---
## 🔐 RBAC Integration
### Tool Access
```python
# In src/core/security.py
AUTHENTICATED_TOOLS = {
"get_user_profile", # ← Available to ALL users
}
```
**Who can use it:** Everyone (about themselves only)
**What they see:** Only their own data
**Security:** Bearer token validates identity
### Data Scoping
- ✅ User sees their own profile
- ❌ User cannot see other users' profiles
- ✅ Data automatically scoped by Bearer token
- ❌ No way to spoof or access others' data
---
## 🧪 Testing
### Test 1: Basic Profile Request
```bash
TOKEN="11836|UAc9YiEKc9zO9MvNHKQqY9WwdkxW7qQyw3mqyNK5"
curl -X POST http://localhost:8002/chat \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"message": "What is my role?"}'
```
**Expected:** AI tells you your role name
### Test 2: Permissions Request
```bash
curl -X POST http://localhost:8002/chat \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"message": "What permissions do I have?"}'
```
**Expected:** AI lists your modules and capabilities
### Test 3: Capabilities Request
```bash
curl -X POST http://localhost:8002/chat \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"message": "What can I do in the system?"}'
```
**Expected:** AI explains your capabilities
---
## 📝 Implementation Details
### File Structure
```
src/mcp_server/tools/user_profile/
├── __init__.py
└── tool.py # Main tool implementation
```
### Key Functions
1. **`filter_user_data()`** - Removes sensitive fields
2. **`format_user_profile_response()`** - Structures data
3. **`_format_permission_name()`** - Makes names user-friendly
4. **`_generate_capabilities_summary()`** - Creates high-level summary
### Data Classes
```python
@dataclass
class UserProfileData:
name: str
email: str
title: str
role: str
status: str
organization_name: str
organization_type: str
permissions: Dict[str, List[str]]
total_permissions: int
modules_access: List[str]
```
---
## 🚀 Benefits
### For Users
- ✅ Clear, understandable answers
- ✅ No technical jargon
- ✅ Grouped by module
- ✅ Quick overview of capabilities
### For Developers
- ✅ Secure by design
- ✅ OWASP compliant
- ✅ Easy to maintain
- ✅ Consistent responses
### For System
- ✅ No sensitive data leaks
- ✅ Proper data scoping
- ✅ Audit-friendly
- ✅ Production-ready
---
## 🔄 Future Enhancements
### Planned Features
- [ ] Permission explanations (what each permission allows)
- [ ] Recent activity summary
- [ ] Hierarchy visualization (org → platform → dealership)
- [ ] Team members list (if manager)
- [ ] Quick actions based on permissions
### Easy to Extend
```python
# Add new capability
if "Reports" in modules:
capabilities.append("Generate and export reports")
# Add new summary field
"recent_activity": {
"last_login": "2 hours ago",
"actions_today": 15
}
```
---
## ✅ Checklist
Before using:
- [ ] Redis running (for user cache)
- [ ] Bearer token authentication working
- [ ] Both servers running
- [ ] Tool registered in RBAC
To test:
- [ ] Ask "What is my role?"
- [ ] Ask "What permissions do I have?"
- [ ] Ask "What can I do?"
- [ ] Verify no sensitive IDs in response
---
## 📚 References
- **OWASP API Security:** https://owasp.org/API-Security/
- **API3:2019 Excessive Data Exposure:** https://owasp.org/API-Security/editions/2019/en/0xa3-excessive-data-exposure/
- **Bearer Token Auth:** `BEARER_TOKEN_AUTH.md`
- **RBAC Guide:** `RBAC_GUIDE.md`
---
## 🎉 Summary
**What it does:** Returns safe, filtered user profile information
**Who can use it:** All authenticated users
**What they see:** Their own data only
**Security:** OWASP compliant, no sensitive data
**Consistency:** Structured responses, reliable answers
**This is production-ready and follows industry best practices!** 🚀
