refactor: store OS-banner dismissal in an extensible user_state_details JSON field

Replace the dedicated UserContactInfo.os_message_dismissed_hash column with a
single user_state_details JSONField that holds an open-ended set of small,
per-user UI flags (dismissed banners, 'don't show again' toggles, ...). The
banner-dismissal hash now lives under the OS_MESSAGE_DISMISSED_KEY key.

This avoids adding a new column (and migration) for every minor per-user toggle;
future ephemeral flags of this kind become a new JSON key with no schema change.
Behavioral/queryable fields (block_execution, token_*, ...) intentionally stay
as columns.

Author: valentijnscholten

dojo/announcement/os_message.py

@@ -9,6 +9,10 @@
 
 logger = logging.getLogger(__name__)
 
+# Key under UserContactInfo.user_state_details holding the hash of the most
+# recently dismissed open-source promo banner.
+OS_MESSAGE_DISMISSED_KEY = "os_message_dismissed_hash"
+
 BUCKET_URL = "https://storage.googleapis.com/defectdojo-os-messages-prod/open_source_message.md"
 CACHE_SECONDS = 3600
 HTTP_TIMEOUT_SECONDS = 2

dojo/announcement/views.py

@@ -10,6 +10,7 @@
 from django.utils.translation import gettext_lazy as _
 from django.views.decorators.http import require_POST
 
+from dojo.announcement.os_message import OS_MESSAGE_DISMISSED_KEY
 from dojo.forms import AnnouncementCreateForm, AnnouncementRemoveForm
 from dojo.models import Announcement, UserAnnouncement, UserContactInfo
 from dojo.utils import add_breadcrumb
@@ -97,9 +98,11 @@ def dismiss_os_message(request):
     token = request.POST.get("token", "").strip()
     if token and re.fullmatch(r"[0-9a-f]{1,64}", token):
         contact = UserContactInfo.objects.get_or_create(user=request.user)[0]
-        if contact.os_message_dismissed_hash != token:
-            contact.os_message_dismissed_hash = token
-            contact.save(update_fields=["os_message_dismissed_hash"])
+        state = contact.user_state_details or {}
+        if state.get(OS_MESSAGE_DISMISSED_KEY) != token:
+            state[OS_MESSAGE_DISMISSED_KEY] = token
+            contact.user_state_details = state
+            contact.save(update_fields=["user_state_details"])
     if request.headers.get("x-requested-with") == "XMLHttpRequest":
         return HttpResponse(status=204)
     referer = request.META.get("HTTP_REFERER")

dojo/context_processors.py

@@ -5,7 +5,7 @@
 from django.contrib import messages
 from django.urls import NoReverseMatch, reverse
 
-from dojo.announcement.os_message import get_os_banner
+from dojo.announcement.os_message import OS_MESSAGE_DISMISSED_KEY, get_os_banner
 from dojo.labels import get_labels
 from dojo.models import System_Settings, UserAnnouncement
 
@@ -80,7 +80,9 @@ def _should_show_ui_toggle_banner(request):
 
 def _os_message_dismissed(user, token):
     contact = getattr(user, "usercontactinfo", None)
-    return contact is not None and contact.os_message_dismissed_hash == token
+    if contact is None:
+        return False
+    return (contact.user_state_details or {}).get(OS_MESSAGE_DISMISSED_KEY) == token
 
 
 def bind_system_settings(request):

dojo/db_migrations/0270_usercontactinfo_os_message_dismissed_hash.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.2.14 on 2026-06-25 00:00
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("dojo", "0269_normalize_blank_finding_components"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="usercontactinfo",
+            name="user_state_details",
+            field=models.JSONField(blank=True, default=dict, editable=False, help_text="Extensible per-user UI state (dismissed banners, 'don't show again' flags, ...)."),
+        ),
+    ]

dojo/db_migrations/0270_usercontactinfo_user_state_details.py

@@ -260,7 +260,11 @@ class UserContactInfo(models.Model):
     ui_use_tailwind = models.BooleanField(default=False, verbose_name=_("Use new UI (beta)"), help_text=_("Opt in to the new Tailwind-based UI. Leave off for the classic UI."))
     token_last_reset = models.DateTimeField(null=True, blank=True, help_text=_("Timestamp of the most recent API token reset for this user."))
     password_last_reset = models.DateTimeField(null=True, blank=True, help_text=_("Timestamp of the most recent password reset for this user."))
-    os_message_dismissed_hash = models.CharField(max_length=64, blank=True, default="", editable=False, help_text=_("Hash of the most recently dismissed open-source promo banner; the banner reappears when the message changes."))
+    # Extensible per-user UI state: dismissed banners, "seen"/"don't show again"
+    # flags, and similar small ephemeral preferences. Store new flags of this kind
+    # as keys here instead of adding a dedicated column per flag (avoids a migration
+    # and a schema column for every minor toggle). Not for queryable/behavioral data.
+    user_state_details = models.JSONField(default=dict, blank=True, editable=False, help_text=_("Extensible per-user UI state (dismissed banners, 'don't show again' flags, ...)."))
 
 
 class System_Settings(models.Model):

dojo/models.py

@@ -276,7 +276,7 @@ def _authed_request(self, *, dismissed_hash="", ui_use_tailwind=True):
         request.user = SimpleNamespace(
             is_authenticated=True,
             usercontactinfo=SimpleNamespace(
-                os_message_dismissed_hash=dismissed_hash,
+                user_state_details={os_message.OS_MESSAGE_DISMISSED_KEY: dismissed_hash},
                 ui_use_tailwind=ui_use_tailwind,
             ),
         )
@@ -331,7 +331,7 @@ def test_post_persists_hash_on_usercontactinfo(self):
         response = self.client.post(self.url, {"token": "abc123def456"}, HTTP_X_REQUESTED_WITH="XMLHttpRequest")
         self.assertEqual(response.status_code, 204)
         contact = UserContactInfo.objects.get(user=self.user)
-        self.assertEqual(contact.os_message_dismissed_hash, "abc123def456")
+        self.assertEqual(contact.user_state_details.get(os_message.OS_MESSAGE_DISMISSED_KEY), "abc123def456")
 
     def test_get_not_allowed(self):
         self.assertEqual(self.client.get(self.url).status_code, 405)
@@ -340,7 +340,8 @@ def test_invalid_token_is_ignored(self):
         response = self.client.post(self.url, {"token": "NOT-HEX!"}, HTTP_X_REQUESTED_WITH="XMLHttpRequest")
         self.assertEqual(response.status_code, 204)
         contact = UserContactInfo.objects.filter(user=self.user).first()
-        self.assertIn(getattr(contact, "os_message_dismissed_hash", ""), ("", None))
+        state = getattr(contact, "user_state_details", {}) or {}
+        self.assertNotIn(os_message.OS_MESSAGE_DISMISSED_KEY, state)
 
     def test_requires_authentication(self):
         self.client.logout()