feat: expand user role model to 4 tiers (admin/creator/operator/user)

[dolho]

• Add require_role(min_role) dependency factory with role hierarchy enforcement
• New GET /api/users and PUT /api/users/{username}/role endpoints (admin-only)
• Agent creation now requires creator role or above
• New email users default to creator role instead of user
• Settings UI: User Management section with role dropdowns per user
• Tests: test_role_model.py covering list users, role update, auth guards
• Docs: role-model.md feature flow, changelog entry

Closes #143

Description

Brief description of changes.

Related Issue

Fixes #(issue number)

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Testing

• I have tested this locally
• New tests added (if applicable)
• All existing tests pass

Checklist

• My code follows the project's style guidelines
• I have updated the documentation (if applicable)
• I have not committed any sensitive data (API keys, credentials, etc.)
• I have added appropriate logging for new functionality

Screenshots (if applicable)

Add screenshots to help explain your changes.

[dolho]

@vybe Ready for review

[vybe]

PR Validation Report — REQUEST CHANGES

Validated by: Trinity PR Validator
Files Changed: 14 (+922/-138)

---

Summary

Category	Status	Notes
Commit Messages	✅	Clear conventional feat: prefix
Roadmap	✅	Closes #143 (P1)
Requirements	❌	requirements.md not updated — ROLE-001 missing
Architecture	⚠️	2 new endpoints undocumented
Feature Flows	⚠️	role-model.md is thorough, but unrelated removals + doc regression
Feature Flow Format	✅	All required sections present
Security Check	✅	No leaked secrets
Code Quality	❌	Authorization regression + scope creep
Requirements Trace	✅	References #143

---

Critical — Block Merge

1. Authorization downgrade on destructive endpoints

Two owner-only endpoints lost their OwnedAgentByName access control:

Endpoint	Before	After	Risk
POST /{agent_name}/queue/clear	OwnedAgentByName (owner-only)	str + get_current_user	Any authenticated user can clear any agent's queue
POST /{agent_name}/queue/release	OwnedAgentByName (owner-only)	str + get_current_user	Any authenticated user can force-release any agent

Two read endpoints also lost AuthorizedAgentByName:

• GET /{agent_name}/stats
• GET /{agent_name}/queue

These changes are unrelated to the role model feature and weaken authorization.

2. Scope creep — unrelated removals

The following removals are not related to the 4-tier role model and should be a separate PR:

• voice_router import + registration (removes VOICE-001)
• event_subscriptions_router import + registration (removes EVT-001)
• VOICE_ENABLED + GEMINI_API_KEY config imports
• slack_transport shutdown logic in lifespan
• Setup token printing in lifespan (SEC #177)
• delete_agent_event_subscriptions() call in agent delete
• Voice Chat, Agent Event Subscriptions, Slack Channel Routing entries removed from feature-flows.md
• #209 changelog content erased
• MCP tool count changed 62 → 45+ without justification

3. Documentation regression in email-authentication.md

The PR removes documentation for OTP rate limiting, IP-based rate limiting on verification, and POST /api/public/verify/confirm. The OTP rate limiting code still exists in src/backend/routers/auth.py (check_otp_rate_limit, record_otp_attempt, lines 102-402). The documentation is now inaccurate.

---

Required Changes

• Restore OwnedAgentByName on POST /{agent_name}/queue/clear and POST /{agent_name}/queue/release (or replace with equivalent role-based auth)
• Restore AuthorizedAgentByName on GET /{agent_name}/stats and GET /{agent_name}/queue
• Split unrelated removals into a separate cleanup PR
• Restore OTP rate limiting documentation in email-authentication.md
• Add ROLE-001 entry to docs/memory/requirements.md
• Add new endpoints (GET /api/users, PUT /api/users/{username}/role) to docs/memory/architecture.md

Suggestions (non-blocking)

• datetime.utcnow() in db/users.py:233 is deprecated in Python 3.12+ — use datetime.now(timezone.utc)
• currentUsername computed property uses fragile @localhost heuristic for admin detection
• test_update_role_invalid_value targets /api/users/admin/role — passes due to self-guard, not role validation. Target a different username.

---

The role model implementation itself (require_role factory, users router, Settings UI, tests) is solid. The issues above are about unrelated changes bundled into this PR.

[dolho]

PR Validation Report — APPROVE

PR: feature/143-role-model → main
Author: Oleksii Dolhov
Branch: feature/143-role-model → main
Files Changed: 16 (+912/-9)

---

Summary

Category	Status	Notes
Commit Messages	✅	feat: + fix: conventional format, clear descriptions
Roadmap	✅	Closes #143 (P1)
Requirements	✅	ROLE-001 added to §2.5 of requirements.md
Architecture	✅	GET /api/users and PUT /api/users/{username}/role documented, users.py router listed
Feature Flows	✅	role-model.md created, indexed in feature-flows.md
Feature Flow Format	⚠️	Uses equivalent section names (Key Functions / API Reference instead of Backend Layer / Security Considerations) — content is present
Security Check	✅	No secrets, tokens, real emails, IPs, or credential files
Code Quality	✅	No unrelated removals, authorization intact, scope is focused
Requirements Trace	✅	References #143, ROLE-001

---

Documentation Checklist

• Commit messages are descriptive
• Roadmap updated (closes feat: Expand user role model (admin / creator / operator / user) #143)
• Requirements updated (§2.5 ROLE-001)
• Architecture updated (2 new endpoints + router)
• Feature flow created (role-model.md)
• Feature flows index updated

Security Checklist

• No API keys or tokens
• No real email addresses (only @router decorator false positives)
• No IP addresses
• No .env files
• No hardcoded secrets
• No credential files

---

Prior Review Issues — All Resolved

• OwnedAgentByName restored on queue/clear and queue/release
• AuthorizedAgentByName restored on stats and queue
• voice_router + event_subscriptions_router restored
• Setup token printing restored
• delete_agent_event_subscriptions restored in agent delete
• OTP rate limiting docs restored in email-authentication.md
• No removals in main.py diff (only additions)

---

Issues Found

Critical (Block Merge)

None.

Warnings (Review Required)

• ⚠️ Feature flow role-model.md uses ## Key Functions / ## API Reference instead of the template's ## Backend Layer / ## Security Considerations — content is equivalent but naming doesn't match template exactly.

Suggestions (Optional)

• datetime.utcnow() remains in 5 other places in db/users.py (pre-existing, not introduced by this PR)

---

Recommendation

APPROVE

All critical issues from the prior review have been resolved. Authorization is intact, scope creep reverted, documentation is complete. The feature flow naming variance is cosmetic — all required content is present.