Add Admin roles

src/Managing.Api/TRADING_CONTROLLER_SECURITY.md

@@ -0,0 +1,125 @@
+# TradingController Security Enhancement
+
+## Overview
+
+The `InitPrivyWallet` endpoint in `TradingController` has been enhanced with admin role security. This ensures that only authorized users can initialize wallet addresses.
+
+## Security Rules
+
+### For Regular Users
+- Can **only** initialize wallet addresses that they own
+- The system verifies ownership by checking if the provided public address exists in one of the user's accounts
+- If a user tries to initialize an address they don't own, they receive a `403 Forbidden` response
+
+### For Admin Users
+- Can initialize **any** wallet address in the system
+- Admin status is determined by the `AdminUsers` environment variable
+- All admin actions are logged for audit purposes
+
+## Implementation Details
+
+### Authentication Flow
+1. **User Authentication**: Endpoint requires valid JWT token
+2. **Admin Check**: System checks if user is in the admin list via `IAdminConfigurationService`
+3. **Ownership Verification**: For non-admin users, verifies address ownership via `IAccountService.GetAccountByKey()`
+4. **Action Logging**: All operations are logged with user context
+
+### Security Validation
+```csharp
+private async Task<bool> CanUserInitializeAddress(string userName, string publicAddress)
+{
+    // Admin users can initialize any address
+    if (_adminService.IsUserAdmin(userName))
+    {
+        return true;
+    }
+
+    // Regular users can only initialize their own addresses
+    var account = await _accountService.GetAccountByKey(publicAddress, true, false);
+    return account?.User?.Name == userName;
+}
+```
+
+## Error Responses
+
+### 401 Unauthorized
+- Missing or invalid JWT token
+- User not found in system
+
+### 403 Forbidden
+- Non-admin user trying to initialize address they don't own
+- Message: "You don't have permission to initialize this wallet address. You can only initialize your own wallet addresses."
+
+### 400 Bad Request
+- Empty or null public address provided
+
+### 500 Internal Server Error
+- System error during wallet initialization
+- Database connectivity issues
+- External service failures
+
+## Admin Configuration
+
+Set admin users via environment variable:
+```bash
+AdminUsers=admin1,admin2,superuser
+```
+
+## Audit Logging
+
+All operations are logged with appropriate context:
+
+**Admin Operations:**
+```
+Admin user {UserName} initializing address {Address}
+```
+
+**User Operations:**
+```
+User {UserName} initializing their own address {Address}
+```
+
+**Security Violations:**
+```
+User {UserName} attempted to initialize address {Address} that doesn't belong to them
+```
+
+## Usage Examples
+
+### Regular User - Own Address
+```bash
+POST /Trading/InitPrivyWallet
+Authorization: Bearer {user-jwt-token}
+Content-Type: application/json
+
+"0x1234567890123456789012345678901234567890"
+```
+**Result**: ✅ Success (if address belongs to user)
+
+### Regular User - Other's Address
+```bash
+POST /Trading/InitPrivyWallet
+Authorization: Bearer {user-jwt-token}
+Content-Type: application/json
+
+"0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
+```
+**Result**: ❌ 403 Forbidden
+
+### Admin User - Any Address
+```bash
+POST /Trading/InitPrivyWallet
+Authorization: Bearer {admin-jwt-token}
+Content-Type: application/json
+
+"0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
+```
+**Result**: ✅ Success (admin can initialize any address)
+
+## Security Benefits
+
+1. **Prevents Unauthorized Access**: Users cannot initialize wallets they don't own
+2. **Admin Oversight**: Admins can manage any wallet for system administration
+3. **Audit Trail**: All actions are logged for compliance and security monitoring
+4. **Clear Authorization**: Explicit permission checks with meaningful error messages
+5. **Secure Configuration**: Admin privileges configured via environment variables, not API calls