Backend: Hide moderator badge behind a feature flag

Add a generic `hidden` flag to badges that excludes a badge from the
GetBadges catalog, from every user's badge list, and from add/remove
notifications, while still awarding and storing it. The moderator badge
is marked hidden. Honoring the flag is gated on the `hide_moderator_badge`
GrowthBook global gate (off by default), so the badge stays visible until
the flag is turned on and can be rolled back instantly.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: aapeliv

app/backend/resources/badges.json

@@ -18,7 +18,8 @@
     {
       "id": "moderator",
       "color": "#c74f5b",
-      "admin_editable": false
+      "admin_editable": false,
+      "hidden": true
     },
     {
       "id": "volunteer",

app/backend/src/couchers/experimentation.py

@@ -188,6 +188,28 @@ def check_gate(context: CouchersContext, gate_name: str) -> bool:
     return _get_growthbook(context).is_on(gate_name)
 
 
+def check_global_gate(gate_name: str) -> bool:
+    """
+    Check if a feature gate is enabled globally, independent of any user.
+
+    Use this for gates that toggle behavior in contexts where there is no authenticated user
+    (background jobs, or open/anonymous endpoints where reading the user id would fail). Evaluated
+    against a stable synthetic identity so every caller gets the same answer - intended for on/off
+    rollouts rather than per-user percentage experiments.
+
+    Returns False if experimentation is disabled, True if EXPERIMENTATION_PASS_ALL_GATES is set.
+    """
+    _check_initialized()
+    if config["EXPERIMENTATION_PASS_ALL_GATES"]:
+        return True
+    if not config["EXPERIMENTATION_ENABLED"]:
+        return False
+    with _state_lock:
+        features = _state["features"]
+        saved_groups = _state["savedGroups"]
+    return GrowthBook(attributes={"id": "global"}, features=features, savedGroups=saved_groups).is_on(gate_name)
+
+
 def get_feature_value[T](context: CouchersContext, feature_name: str, default: T) -> T:
     """
     Get the value of a feature for the user in this context.

app/backend/src/couchers/helpers/badges.py

@@ -7,7 +7,7 @@
 from couchers.models.notifications import NotificationTopicAction
 from couchers.notifications.notify import notify
 from couchers.proto import notification_data_pb2
-from couchers.resources import get_badge_dict
+from couchers.resources import get_badge_dict, hidden_badges_active
 
 
 def user_add_badge(session: Session, user_id: int, badge_id: str, do_notify: bool = True) -> None:
@@ -19,7 +19,7 @@ def user_add_badge(session: Session, user_id: int, badge_id: str, do_notify: boo
         return
     session.add(UserBadge(user_id=user_id, badge_id=badge_id))
     session.flush()
-    if do_notify:
+    if do_notify and not (badge.hidden and hidden_badges_active()):
         context = make_background_user_context(user_id=user_id)
         notify(
             session,
@@ -39,16 +39,17 @@ def user_remove_badge(session: Session, user_id: int, badge_id: str) -> None:
     badge = get_badge_dict()[badge_id]
     session.execute(delete(UserBadge).where(UserBadge.user_id == user_id, UserBadge.badge_id == badge.id))
     session.flush()
-    context = make_background_user_context(user_id=user_id)
-    notify(
-        session,
-        user_id=user_id,
-        topic_action=NotificationTopicAction.badge__remove,
-        key=badge.id,
-        data=notification_data_pb2.BadgeRemove(
-            badge_id=badge.id,
-            badge_name=context.localization.localize_string(f"badges.{badge.id}_name"),
-            badge_description=context.localization.localize_string(f"badges.{badge.id}_description"),
-        ),
-    )
+    if not (badge.hidden and hidden_badges_active()):
+        context = make_background_user_context(user_id=user_id)
+        notify(
+            session,
+            user_id=user_id,
+            topic_action=NotificationTopicAction.badge__remove,
+            key=badge.id,
+            data=notification_data_pb2.BadgeRemove(
+                badge_id=badge.id,
+                badge_name=context.localization.localize_string(f"badges.{badge.id}_name"),
+                badge_description=context.localization.localize_string(f"badges.{badge.id}_description"),
+            ),
+        )
     session.commit()

app/backend/src/couchers/resources.py

@@ -1,6 +1,7 @@
 import functools
 import json
 import logging
+from collections.abc import Iterable
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, cast
@@ -11,6 +12,7 @@
 
 from couchers.config import config
 from couchers.db import session_scope
+from couchers.experimentation import check_global_gate
 from couchers.models import Language, Region, TimezoneArea
 
 logger = logging.getLogger(__name__)
@@ -77,6 +79,9 @@ class Badge:
     id: str
     color: str
     admin_editable: bool
+    # hidden badges are still awarded and stored, but never shown to clients (no catalog entry,
+    # not listed on user profiles, and no add/remove notification)
+    hidden: bool = False
 
 
 @functools.cache
@@ -88,6 +93,27 @@ def get_badge_dict() -> dict[str, Badge]:
     return {badge.id: badge for badge in badges}
 
 
+# gate controlling the rollout of hiding hidden badges; off by default so badges stay visible
+HIDE_MODERATOR_BADGE_GATE = "hide_moderator_badge"
+
+
+def hidden_badges_active() -> bool:
+    """Whether badges marked hidden should actually be hidden, per the rollout gate."""
+    return check_global_gate(HIDE_MODERATOR_BADGE_GATE)
+
+
+def filter_hidden_badge_ids(badge_ids: Iterable[str]) -> list[str]:
+    """
+    Drop hidden badge ids from a list of badge ids, preserving order.
+
+    No-op while the rollout gate is off, so hidden badges stay visible until the flag is turned on.
+    """
+    if not hidden_badges_active():
+        return list(badge_ids)
+    badge_dict = get_badge_dict()
+    return [badge_id for badge_id in badge_ids if badge_id in badge_dict and not badge_dict[badge_id].hidden]
+
+
 @functools.cache
 def get_static_badge_dict() -> dict[str, list[int]]:
     """

app/backend/src/couchers/servicers/admin.py

@@ -47,7 +47,7 @@
 from couchers.notifications.notify import notify
 from couchers.proto import admin_pb2, admin_pb2_grpc, api_pb2, notification_data_pb2
 from couchers.proto.internal import jobs_pb2
-from couchers.resources import get_badge_dict
+from couchers.resources import filter_hidden_badge_ids, get_badge_dict
 from couchers.servicers.api import user_model_to_pb
 from couchers.servicers.auth import create_session
 from couchers.servicers.events import generate_event_delete_notifications
@@ -148,7 +148,7 @@ def _user_to_details(session: Session, user: User) -> admin_pb2.UserDetails:
         deleted=user.deleted_at is not None,
         shadowed=user.shadowed_at is not None,
         do_not_email=user.do_not_email,
-        badges=[badge.badge_id for badge in user.badges],
+        badges=filter_hidden_badge_ids(badge.badge_id for badge in user.badges),
         **get_strong_verification_fields(session, user),
         has_passport_sex_gender_exception=user.has_passport_sex_gender_exception,
         pending_mod_notes_count=user.mod_notes.where(ModNote.is_pending).count(),

app/backend/src/couchers/servicers/api.py

@@ -52,7 +52,7 @@
 from couchers.proto import api_pb2, api_pb2_grpc, media_pb2, notification_data_pb2, requests_pb2
 from couchers.rate_limits.check import process_rate_limits_and_check_abort
 from couchers.rate_limits.definitions import RATE_LIMIT_HOURS
-from couchers.resources import get_badge_dict, language_is_allowed, region_is_allowed
+from couchers.resources import filter_hidden_badge_ids, get_badge_dict, language_is_allowed, region_is_allowed
 from couchers.servicers.blocking import is_not_visible
 from couchers.sql import (
     moderation_state_column_visible,
@@ -1159,9 +1159,11 @@ def user_model_to_pb(
         avatar_url=avatar_upload.full_url if avatar_upload else None,
         avatar_thumbnail_url=avatar_upload.thumbnail_url if avatar_upload else None,
         profile_gallery_id=db_user.profile_gallery_id,
-        badges=session.execute(select(UserBadge.badge_id).where(UserBadge.user_id == db_user.id).order_by(UserBadge.id))
-        .scalars()
-        .all(),
+        badges=filter_hidden_badge_ids(
+            session.execute(select(UserBadge.badge_id).where(UserBadge.user_id == db_user.id).order_by(UserBadge.id))
+            .scalars()
+            .all()
+        ),
         **get_strong_verification_fields(session, db_user),
         **response_rate_to_pb(response_rate),  # type: ignore[arg-type]
     )

app/backend/src/couchers/servicers/public.py

@@ -25,7 +25,7 @@
 from couchers.models.uploads import get_avatar_upload
 from couchers.proto import api_pb2, public_pb2, public_pb2_grpc
 from couchers.proto.google.api import httpbody_pb2
-from couchers.resources import get_static_badge_dict
+from couchers.resources import filter_hidden_badge_ids, get_static_badge_dict
 from couchers.servicers.api import fluency2api, hostingstatus2api, meetupstatus2api, user_model_to_pb
 from couchers.servicers.gis import _statement_to_geojson_response
 from couchers.utils import Timestamp_from_datetime, not_none, now
@@ -222,7 +222,7 @@ def GetPublicUser(
                     joined=Timestamp_from_datetime(user.display_joined),
                     hosting_status=hostingstatus2api[user.hosting_status],
                     meetup_status=meetupstatus2api[user.meetup_status],
-                    badges=[badge.badge_id for badge in user.badges],
+                    badges=filter_hidden_badge_ids(badge.badge_id for badge in user.badges),
                 )
             )
 
@@ -256,7 +256,7 @@ def GetPublicUser(
                     regions_lived=[region.code for region in user.regions_lived],
                     avatar_url=avatar_upload.full_url if avatar_upload else None,
                     avatar_thumbnail_url=avatar_upload.thumbnail_url if avatar_upload else None,
-                    badges=[badge.badge_id for badge in user.badges],
+                    badges=filter_hidden_badge_ids(badge.badge_id for badge in user.badges),
                 )
             )
         raise RuntimeError(user.public_visibility)

app/backend/src/couchers/servicers/resources.py

@@ -11,6 +11,7 @@
     get_language_dict,
     get_region_dict,
     get_terms_of_service,
+    hidden_badges_active,
 )
 
 logger = logging.getLogger(__name__)
@@ -64,6 +65,7 @@ def GetLanguages(
     def GetBadges(
         self, request: empty_pb2.Empty, context: CouchersContext, session: Session
     ) -> resources_pb2.GetBadgesRes:
+        hide_hidden = hidden_badges_active()
         return resources_pb2.GetBadgesRes(
             badges=[
                 resources_pb2.Badge(
@@ -73,5 +75,6 @@ def GetBadges(
                     color=badge.color,
                 )
                 for badge in get_badge_dict().values()
+                if not (hide_hidden and badge.hidden)
             ]
         )

app/backend/src/tests/test_api.py

@@ -5,6 +5,7 @@
 from google.protobuf import empty_pb2, wrappers_pb2
 from sqlalchemy import func, select, update
 
+from couchers.config import config
 from couchers.db import session_scope
 from couchers.helpers.badges import user_add_badge
 from couchers.jobs.handlers import update_badges
@@ -1573,6 +1574,68 @@ def test_badges(db):
         assert res2.user_ids == [2]
 
 
+def test_hidden_badge_is_awarded_but_not_shown(db):
+    """
+    With the rollout gate on (tests pass all gates), the moderator badge is awarded to superusers
+    and stored, but not shown to clients or notified.
+    """
+    # create dummies first so the superuser isn't a static founder/board_member (user ids 1, 2)
+    generate_user(last_donated=None)
+    generate_user(last_donated=None)
+    superuser, token = generate_user(is_superuser=True, last_donated=None)
+
+    update_badges(empty_pb2.Empty())
+
+    with session_scope() as session:
+        # the badge row is still created
+        assert (
+            session.execute(
+                select(func.count())
+                .select_from(UserBadge)
+                .where(UserBadge.user_id == superuser.id, UserBadge.badge_id == "moderator")
+            ).scalar()
+            == 1
+        )
+        # but the user gets no notification about it
+        assert (
+            session.execute(
+                select(func.count()).select_from(Notification).where(Notification.user_id == superuser.id)
+            ).scalar()
+            == 0
+        )
+
+    # and it does not appear on the user's profile
+    with api_session(token) as api:
+        assert "moderator" not in api.GetUser(api_pb2.GetUserReq(user=superuser.username)).badges
+
+
+def test_hidden_badge_is_shown_when_rollout_gate_off(db, monkeypatch):
+    """With the rollout gate off, the moderator badge behaves as before: shown and notified."""
+    # disable experimentation so the global gate evaluates to off (rollback / pre-rollout state)
+    monkeypatch.setitem(config, "EXPERIMENTATION_PASS_ALL_GATES", False)
+    monkeypatch.setitem(config, "EXPERIMENTATION_ENABLED", False)
+
+    # create dummies first so the superuser isn't a static founder/board_member (user ids 1, 2)
+    generate_user(last_donated=None)
+    generate_user(last_donated=None)
+    superuser, token = generate_user(is_superuser=True, last_donated=None)
+
+    update_badges(empty_pb2.Empty())
+
+    with session_scope() as session:
+        # the badge add is notified
+        assert (
+            session.execute(
+                select(func.count()).select_from(Notification).where(Notification.user_id == superuser.id)
+            ).scalar()
+            == 1
+        )
+
+    # and it appears on the user's profile
+    with api_session(token) as api:
+        assert "moderator" in api.GetUser(api_pb2.GetUserReq(user=superuser.username)).badges
+
+
 def test_user_add_badge_is_idempotent(db):
     """Test that adding a badge a user already has is a no-op and doesn't send a duplicate notification."""
     user, _ = generate_user()

app/backend/src/tests/test_resources.py

@@ -50,12 +50,11 @@ def test_GetBadges(db):
         badges = api.GetBadges(empty_pb2.Empty()).badges
         badges_dict = {b.id: b for b in badges}
 
-        # Check that all expected badges are present
+        # Check that all expected badges are present (the hidden "moderator" badge is excluded)
         expected_badge_ids = {
             "founder",
             "board_member",
             "past_board_member",
-            "moderator",
             "volunteer",
             "past_volunteer",
             "donor",
@@ -72,13 +71,6 @@ def test_GetBadges(db):
         assert founder.description == "This user is one of the two founders of Couchers.org"
         assert founder.color == "#e47701"
 
-        # Check another badge to ensure translations are working
-        moderator = badges_dict["moderator"]
-        assert moderator.id == "moderator"
-        assert moderator.name == "Moderator"
-        assert moderator.description == "This user is a moderator of Couchers.org"
-        assert moderator.color == "#c74f5b"
-
         # Check strong_verification badge
         strong_verification = badges_dict["strong_verification"]
         assert strong_verification.id == "strong_verification"