feat(tests,users): blocking procedure-suggestion review on test detail, multi-role switcher, Power Automate webhook payload

- A lead opening a test with a pending procedure suggestion awaiting
  their review now gets a blocking popup (approve/reject only) instead
  of discovering it later in a separate queue.
- Users can be granted more than one role via extra_roles; only one is
  ever active at a time (no permission mixing) and a top-bar switcher
  lets the user swap which one, taking effect immediately since role
  is read fresh from the DB on every request.
- The password-setup/reset webhook now posts the agreed Power Automate
  contract ({to, subject, body} with the platform's standard greeting
  and signature template) and supports an admin-configured API key
  sent as an x-api-key header.

backend/app/services/password_setup_service.py

@@ -27,8 +27,26 @@ from app.models.user import User
 logger = logging.getLogger(__name__)
 
 _WEBHOOK_URL_CONFIG_KEY = "password_setup.webhook_url"
+_WEBHOOK_API_KEY_CONFIG_KEY = "password_setup.webhook_api_key"
 _TOKEN_TTL = timedelta(hours=24)
 
+# Standard footer appended to every Power-Automate-delivered notification
+# email, matching the platform's established template.
+_EMAIL_SIGNATURE = (
+    "\n\nRegards,\n"
+    "AEGIS Security Platform\n"
+    "Purple Team Engineering\n"
+    "Owned and operated by Enterprise Corp.\n\n"
+    "Assume breach. Validate controls. Improve continuously.\n\n"
+    "This is an automated notification. Please do not reply."
+)
+
+
+def _build_email_body(full_name: str | None, message: str) -> str:
+    """Wrap *message* in the standard greeting + signature template."""
+    greeting = full_name or "there"
+    return f"HI {greeting}\n\n{message}{_EMAIL_SIGNATURE}"
+
 
 def _read_system_config(db: Session, key: str) -> str | None:
     from app.models.system_config import SystemConfig  # avoid circular at import time
@@ -37,6 +55,16 @@ def _read_system_config(db: Session, key: str) -> str | None:
     return row.value if row else None
 
 
+def _write_system_config(db: Session, key: str, value: str) -> None:
+    from app.models.system_config import SystemConfig
+
+    row = db.query(SystemConfig).filter(SystemConfig.key == key).first()
+    if row:
+        row.value = value
+    else:
+        db.add(SystemConfig(key=key, value=value))
+
+
 def get_password_webhook_url(db: Session) -> str | None:
     """Return the configured Power-Automate-style webhook URL, or None."""
     return _read_system_config(db, _WEBHOOK_URL_CONFIG_KEY) or None
@@ -44,13 +72,17 @@ def get_password_webhook_url(db: Session) -> str | None:
 
 def set_password_webhook_url(db: Session, url: str) -> None:
     """Persist the webhook URL. Does not commit; caller commits."""
-    from app.models.system_config import SystemConfig
+    _write_system_config(db, _WEBHOOK_URL_CONFIG_KEY, url)
 
-    row = db.query(SystemConfig).filter(SystemConfig.key == _WEBHOOK_URL_CONFIG_KEY).first()
-    if row:
-        row.value = url
-    else:
-        db.add(SystemConfig(key=_WEBHOOK_URL_CONFIG_KEY, value=url))
+
+def get_password_webhook_api_key(db: Session) -> str | None:
+    """Return the configured webhook API key, or None."""
+    return _read_system_config(db, _WEBHOOK_API_KEY_CONFIG_KEY) or None
+
+
+def set_password_webhook_api_key(db: Session, api_key: str) -> None:
+    """Persist the webhook API key. Does not commit; caller commits."""
+    _write_system_config(db, _WEBHOOK_API_KEY_CONFIG_KEY, api_key)
 
 
 def create_setup_token(db: Session, user: User) -> PasswordSetupToken:
@@ -88,15 +120,26 @@ def send_password_setup_email(db: Session, user: User) -> None:
 
     token = create_setup_token(db, user)
     set_password_url = f"{settings.PLATFORM_URL}/set-password?token={token.token}"
+    is_reset = not user.must_change_password
+    subject = "Reset Your Password" if is_reset else "Set Your Password"
+    message = (
+        f'Click the link below to {"reset" if is_reset else "set"} your Aegis password:\n\n'
+        f"{set_password_url}\n\n"
+        "This link expires in 24 hours and can only be used once."
+    )
+
+    api_key = get_password_webhook_api_key(db)
+    headers = {"x-api-key": api_key} if api_key else {}
 
     try:
         requests.post(
             webhook_url,
             json={
-                "email": user.email,
-                "full_name": user.full_name,
-                "set_password_url": set_password_url,
+                "to": user.email,
+                "subject": subject,
+                "body": _build_email_body(user.full_name, message),
             },
+            headers=headers,
             timeout=10,
         )
     except requests.RequestException:

backend/app/services/procedure_suggestion_service.py

@@ -131,11 +131,17 @@ def create_suggestion_from_submission(db: Session, test: Test, team: str) -> Pro
     return suggestion
 
 
-def list_pending_suggestions(db: Session, *, team: str | None = None) -> list[ProcedureSuggestion]:
-    """List pending suggestions, optionally filtered to one team."""
+def list_pending_suggestions(
+    db: Session, *, team: str | None = None, source_test_id: uuid.UUID | None = None,
+) -> list[ProcedureSuggestion]:
+    """List pending suggestions, optionally filtered to one team and/or the
+    specific test that originated them (used to block a lead's test-detail
+    view on a suggestion awaiting their review)."""
     query = db.query(ProcedureSuggestion).filter(ProcedureSuggestion.status == "pending")
     if team is not None:
         query = query.filter(ProcedureSuggestion.team == team)
+    if source_test_id is not None:
+        query = query.filter(ProcedureSuggestion.source_test_id == source_test_id)
     return query.order_by(ProcedureSuggestion.created_at.asc()).all()
 
 

backend/app/services/user_service.py

@@ -159,6 +159,13 @@ def update_user(db: Session, user_id: uuid.UUID, **fields: object) -> User:
             f"Invalid role '{update_data['role']}'. Must be one of: {', '.join(sorted(VALID_ROLES))}"
         )
 
+    if update_data.get("extra_roles") is not None:
+        invalid = [r for r in update_data["extra_roles"] if r not in VALID_ROLES]
+        if invalid:
+            raise BusinessRuleViolation(
+                f"Invalid role(s) {', '.join(invalid)}. Must be one of: {', '.join(sorted(VALID_ROLES))}"
+            )
+
     # Check: "password" in update_data
     if "password" in update_data:
         # Assign update_data["hashed_password"] = hash_password(str(update_data.pop("password")))
@@ -171,3 +178,25 @@ def update_user(db: Session, user_id: uuid.UUID, **fields: object) -> User:
 
     # Return user
     return user
+
+
+def switch_active_role(db: Session, user: User, new_role: str) -> User:
+    """Swap *user*'s currently-active role with one from their extra_roles.
+
+    Roles never mix — the user acts under exactly one role at a time, this
+    just changes which one. Raises BusinessRuleViolation if new_role isn't
+    one this user has been granted. Does not commit; caller commits.
+    """
+    available = {user.role, *(user.extra_roles or [])}
+    if new_role not in available:
+        raise BusinessRuleViolation(f"Role '{new_role}' is not available to this user")
+
+    if new_role == user.role:
+        return user
+
+    old_role = user.role
+    remaining = [r for r in (user.extra_roles or []) if r != new_role]
+    remaining.append(old_role)
+    user.role = new_role
+    user.extra_roles = remaining
+    return user