feat-2187: add additional default roles while bootstrap

[KKNithin]

resolves new feature request #2187

Closes #2187

[crivetimihai]

Review Feedback

Hi @KKNithin, thank you for this feature addition. I've done a deep review and found some issues that need to be addressed before merging.

Critical Bug: Missing Early Exit

The code logs a warning when the file doesn't exist but still tries to open it:

# bootstrap_db.py lines 276-280
if not additonal_default_roles_path.exists():
    logger.warning(f"Catalog file not found: {additonal_default_roles_path}")
    # BUG: No return/continue here!

with open(additonal_default_roles_path, "r", encoding="utf-8") as f:  # Will fail!

Compare to the correct pattern already in the codebase at catalog_service.py:73-75:

if not catalog_path.exists():
    logger.warning(f"Catalog file not found: {catalog_path}")
    return {"catalog_servers": [], "categories": [], "auth_types": []}  # Returns early!

Fix: Add early exit after the warning (e.g., don't try to open the file if it doesn't exist).

---

Invalid JSON Example in .env.example

The example JSON uses Python syntax, not valid JSON:

# Current (INVALID JSON):
#     "is_system_role": True,   # Python True, not JSON true
# },                             # Trailing comma not allowed in JSON

Fix: Use valid JSON syntax:

[{
    "name": "example_role_1",
    "description": "Read-only access to resources",
    "scope": "team",
    "permissions": ["teams.join", "tools.read", "resources.read"],
    "is_system_role": true
}]

If a user copies the current example, their JSON file will fail to parse with a confusing error.

---

Other Issues

Issue	Location	Fix
Typo: additonal_ should be additional_	bootstrap_db.py (4 occurrences)	Rename variables
Wrong message: "Catalog file not found"	bootstrap_db.py:277	Change to "Additional roles file not found"
Missing newline at end of file	.env.example	Add newline

---

What Works Well

• Feature is disabled by default (safe)
• Good test coverage
• Permissions are validated by role_service.create_role()
• Helm chart updated
• Documentation in .env.example

---

Please address these issues and I'll re-review. Let me know if you have any questions!

[KKNithin]

@crivetimihai I have resolved your code review comments

can you please review it for approval

[madhav165]

@crivetimihai The functionality of adding roles worked when I tested by updating the .env variables and crated the role JSON.

However, the new roles can't be used without more changes to the RBAC system which is hardcoded to look for roles in EmailTeamMember rather than UserRoles. Team member management also does not link them to the Roles in the code.

[crivetimihai]

PR Review & Fixes Summary

This PR has been rebased onto main and includes several fixes identified during code review.

Original Feature

Load custom RBAC roles from a JSON configuration file during database bootstrap, allowing organizations to pre-configure roles before deployment.

Fixes Applied

1. Path Resolution Bug (Medium)

• Issue: Path(__file__).parent.parent.parent resolved one level above repo root
• Fix: Changed to Path(__file__).resolve().parent.parent to correctly resolve to project root
• Also: Added improved logging showing all attempted paths when file not found

2. JSON Structure Validation (Medium)

• Issue: No validation of JSON structure could crash bootstrap with malformed config
• Fix: Added validation that:
  • JSON must be an array (not dict)
  • Each entry must be a dict
  • Required keys: name, scope, permissions
  • Invalid entries are skipped with warnings; valid entries are processed

3. Optional Fields Bug (Medium)

• Issue: description and is_system_role accessed via role_def["key"] causing KeyError for minimal roles
• Fix: Use .get() with defaults:
  • description defaults to ""
  • is_system_role defaults to False

Tests Added

• test_bootstrap_roles_with_minimal_valid_role - Verifies roles with only required fields work
• test_bootstrap_roles_with_dict_instead_of_list - Verifies error when JSON is dict
• test_bootstrap_roles_with_missing_required_keys - Verifies invalid entries are skipped

Documentation Added

• docs/docs/manage/rbac.md - New "Bootstrap Custom Roles" section with Docker Compose and Kubernetes examples
• docs/docs/architecture/adr/036-bootstrap-custom-roles.md - Full ADR documenting design decisions

Commits

1bb720758 fix: Make description and is_system_role optional for bootstrap roles
34bed2bd3 fix: Improve bootstrap roles validation and documentation
2a89ed60f feat-2187: test fix
1d7c9ce11 feat-2187: fixing review comments
3f33ff01f feat-2187: fixing review comments
a4a590f5c feat-2187: fix lint issues
61779ec9f feat-2187: add additional default roles while bootstrap

Test Results

All 35 bootstrap_db tests pass.

Docker Compose Testing

Verified end-to-end:

• Custom roles loaded from JSON file ✅
• Roles created with correct permissions ✅
• Error handling for invalid JSON ✅
• Graceful degradation when file not found ✅