feat(tokens): add admin-delegated token creation with user_email parameter

[bogdanmariusc10]

🔗 Related Issue

Closes #4389

---

📝 Summary

This PR adds admin-delegated token creation capability to the POST /tokens endpoint by introducing an optional user_email parameter. This enables platform admins to create API tokens on behalf of other users, resolving a critical portal architecture blocker where admin portals need to create tokens for logged-in users.

Key Changes:

• Added user_email (Optional[EmailStr]) parameter to TokenCreateRequest schema
• Implemented admin authorization requiring un-narrowed platform admin access
• Added audit logging for all admin-delegated token creation operations
• Maintained all existing security invariants (Management Plane isolation, interactive session requirement)

Security Model:

• Requires is_admin=True AND token_teams=None (un-narrowed admin)
• Narrowed admin sessions cannot delegate token creation
• API tokens still blocked from token management (Management Plane isolation)
• Email validation via Pydantic EmailStr type
• Comprehensive audit trail via structured logging

---

🏷️ Type of Change

• Feature / Enhancement
• Bug fix
• Documentation
• Refactor
• Chore (deps, CI, tooling)
• Other (describe below)

---

🧪 Verification

Check	Command	Status
Lint suite	make lint	✅ Pass
Unit tests	make test	✅ Pass
Coverage ≥ 80%	make coverage	✅ Pass

---

✅ Checklist

• Code formatted (make black isort pre-commit)
• Tests added/updated for changes
• Documentation updated (inline docstrings)
• No secrets or credentials committed

---

📓 Notes

Implementation Details

Files Modified:

1. mcpgateway/schemas.py - Added user_email parameter
2. mcpgateway/routers/tokens.py - Admin authorization logic
3. tests/unit/mcpgateway/routers/test_tokens.py - Updated 2 tests for compatibility
4. tests/unit/mcpgateway/routers/test_tokens_admin_delegation.py - New test file with 7 test cases

Security Invariants Verified

✅ Management Plane Isolation: _require_authenticated_session() called before any logic

• Blocks auth_method == "api_token" with 403 Forbidden
• Enforces interactive session requirement

✅ Un-narrowed Admin Requirement: Lines 144-151

• Checks token_teams is not None and rejects with 403
• Prevents narrowed admin sessions from delegation

✅ Audit Trail: Lines 153-157

• Structured logging via logger.info() for all delegated operations
• Includes admin email and target user email

✅ Email Validation: Schema line 6783

• Pydantic EmailStr type enforces valid email format

Usage Example

# Admin creates token for another user
POST /tokens
Authorization: Bearer <admin_session_token>
Content-Type: application/json

{
  "name": "Portal User Token",
  "user_email": "[email protected]",  # NEW: Admin-only parameter
  "description": "Token for portal user",
  "expires_in_days": 30,
  "tags": ["portal", "delegated"]
}

Backward Compatibility

✅ Fully backward compatible - user_email is optional and defaults to None
✅ Existing API calls work unchanged
✅ No breaking changes to existing functionality