Skip to content

armgit / mwmbl

Public Imported from GitHub
0

An open source, non-profit web search engine

Add marketing email opt-in with GDPR-aligned consent tracking

Daoud Clarke862bc0f49b80
diff --git a/mwmbl/admin.py b/mwmbl/admin.py
index 42b0dc5..214a21f 100644
--- a/mwmbl/admin.py
+++ b/mwmbl/admin.py
@@ -3,7 +3,7 @@ from django.contrib import admin
from django.contrib.admin import ModelAdmin
from django.contrib.auth.admin import UserAdmin
-from mwmbl.models import MwmblUser, OldIndex, Curation, FlagCuration, DomainSubmission, ApiKey, generate_api_key
+from mwmbl.models import MwmblUser, OldIndex, Curation, FlagCuration, DomainSubmission, ApiKey, MarketingConsent, generate_api_key
class ApiKeyForm(forms.ModelForm):
@@ -50,4 +50,11 @@ admin.site.register(Curation, ModelAdmin)
admin.site.register(OldIndex, ModelAdmin)
admin.site.register(FlagCuration, ModelAdmin)
admin.site.register(DomainSubmission, ModelAdmin)
+class MarketingConsentAdmin(ModelAdmin):
+ list_display = ("user", "source", "opted_in", "timestamp")
+ list_filter = ("source", "opted_in")
+ readonly_fields = ("user", "source", "opted_in", "timestamp")
+
+
admin.site.register(ApiKey, ApiKeyAdmin)
+admin.site.register(MarketingConsent, MarketingConsentAdmin)
diff --git a/mwmbl/migrations/0024_marketingconsent.py b/mwmbl/migrations/0024_marketingconsent.py
new file mode 100644
index 0000000..fcae3b4
--- /dev/null
+++ b/mwmbl/migrations/0024_marketingconsent.py
@@ -0,0 +1,28 @@
+# Generated by Django 5.2.13 on 2026-06-25 07:21
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+ dependencies = [
+ ('mwmbl', '0023_userbilling_cancel_at_period_end'),
+ ]
+
+ operations = [
+ migrations.CreateModel(
+ name='MarketingConsent',
+ fields=[
+ ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+ ('source', models.CharField(choices=[('GUI', 'Consumer site (mwmbl.org)'), ('API', 'Developer site (developer.mwmbl.org)')], max_length=10)),
+ ('opted_in', models.BooleanField()),
+ ('timestamp', models.DateTimeField(auto_now_add=True)),
+ ('user', models.ForeignKey(null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='marketing_consents', to=settings.AUTH_USER_MODEL)),
+ ],
+ options={
+ 'indexes': [models.Index(fields=['user', 'source', '-timestamp'], name='mwmbl_marke_user_id_c00b4e_idx')],
+ },
+ ),
+ ]
diff --git a/mwmbl/models.py b/mwmbl/models.py
index 32e38a1..169abcd 100644
--- a/mwmbl/models.py
+++ b/mwmbl/models.py
@@ -208,6 +208,33 @@ class UserAgreement(models.Model):
]
+class MarketingSource(models.TextChoices):
+ GUI = "GUI", "Consumer site (mwmbl.org)"
+ API = "API", "Developer site (developer.mwmbl.org)"
+
+
+class MarketingConsent(models.Model):
+ """
+ Append-only audit trail of marketing email consent decisions.
+
+ Every opt-in and opt-out writes a new row; the current state for a source is
+ the `opted_in` of the latest row. Mirrors UserAgreement.
+ """
+ # SET_NULL (not CASCADE) so the consent proof survives account deletion,
+ # matching UserAgreement.
+ user = models.ForeignKey(
+ MwmblUser, on_delete=models.SET_NULL, null=True, related_name="marketing_consents"
+ )
+ source = models.CharField(max_length=10, choices=MarketingSource.choices)
+ opted_in = models.BooleanField()
+ timestamp = models.DateTimeField(auto_now_add=True)
+
+ class Meta:
+ indexes = [
+ models.Index(fields=["user", "source", "-timestamp"]),
+ ]
+
+
class SearchResultVote(models.Model):
VOTE_TYPES = {
"upvote": "User upvoted this result",
diff --git a/mwmbl/platform/api.py b/mwmbl/platform/api.py
index 05cb314..e00d086 100644
--- a/mwmbl/platform/api.py
+++ b/mwmbl/platform/api.py
@@ -4,6 +4,8 @@ from allauth.account.adapter import get_adapter
from allauth.account.models import EmailConfirmationHMAC
from allauth.account.utils import setup_user_email, send_email_confirmation
from django.conf import settings
+from django.core import signing
+from django.http import HttpResponse
from django.utils import timezone
from ninja import Router
from ninja.pagination import paginate
@@ -15,7 +17,7 @@ from polar_sdk.webhooks import validate_event, WebhookVerificationError
from mwmbl.exceptions import InvalidRequest
from mwmbl.search_auth import invalidate_api_key_cache, invalidate_user_api_key_cache
-from mwmbl.models import AgreementType, MwmblUser, DomainSubmission, SearchResultVote, ApiKey, UsageBucket, UserBilling, UserAgreement, generate_username
+from mwmbl.models import AgreementType, MwmblUser, DomainSubmission, SearchResultVote, ApiKey, UsageBucket, UserBilling, UserAgreement, MarketingConsent, MarketingSource, generate_username
from mwmbl.platform.schemas import (
Registration, ConfirmEmail, DomainSubmissionSchema, UpdateDomainSubmission,
VoteRequest, VoteRemoveRequest, VoteStatsRequest, VoteResponse, VoteStats, UserVoteHistory,
@@ -23,6 +25,7 @@ from mwmbl.platform.schemas import (
UserProfileResponse, SubscriptionResponse, CheckoutRequest, CheckoutResponse, ChangePlanRequest,
ForgotPasswordRequest, ResetPasswordRequest,
AgreementAcceptRequest, AgreementResponse,
+ MarketingConsentRequest, MarketingConsentResponse,
)
logger = logging.getLogger(__name__)
@@ -63,6 +66,9 @@ def register(request, registration: Registration):
if registration.agreements:
_record_agreements(user, registration.agreements)
+ if registration.source is not None:
+ _record_marketing_consent(user, registration.source, registration.marketing_opt_in)
+
setup_user_email(request, user, [])
send_email_confirmation(request, user, signup=True)
@@ -360,6 +366,21 @@ def _record_agreements(user: MwmblUser, agreement_types: list) -> None:
)
+def _record_marketing_consent(user: MwmblUser, source: MarketingSource, opted_in: bool) -> None:
+ MarketingConsent.objects.create(user=user, source=source, opted_in=opted_in)
+
+
+_UNSUBSCRIBE_SALT = "marketing-unsubscribe"
+
+
+def make_unsubscribe_token(user: MwmblUser, source: MarketingSource) -> str:
+ """
+ Build a signed, URL-safe token identifying a (user, source) pair for one-click
+ unsubscribe. No expiry: unsubscribe links in old emails must keep working.
+ """
+ return signing.dumps({"user_id": user.id, "source": source}, salt=_UNSUBSCRIBE_SALT)
+
+
def _require_current_agreement(user: MwmblUser, agreement_type: AgreementType) -> None:
current_version = settings.CURRENT_AGREEMENT_VERSIONS.get(agreement_type)
accepted = UserAgreement.objects.filter(
@@ -456,6 +477,110 @@ def get_agreement_history(request) -> list[AgreementResponse]:
return UserAgreement.objects.filter(user=request.user).order_by("-accepted_at")
+# ---------------------------------------------------------------------------
+# Marketing consent
+# ---------------------------------------------------------------------------
+
+ "/marketing-consent",
+ auth=JWTAuth(),
+ response=list[MarketingConsentResponse],
+ summary="Get marketing email consent",
+ description=(
+ "Returns the current marketing email consent state for each source the user has a "
+ "record for (`GUI` = mwmbl.org, `API` = developer.mwmbl.org). The state for a source "
+ "is its most recently recorded decision. Sources with no record are omitted. "
+ "Requires a verified account."
+ ),
+ tags=["Marketing"],
+)
+def get_marketing_consent(request) -> list[MarketingConsentResponse]:
+ check_email_verified(request)
+ result = []
+ for source in MarketingSource:
+ latest = (
+ MarketingConsent.objects.filter(user=request.user, source=source)
+ .order_by("-timestamp")
+ .first()
+ )
+ if latest:
+ result.append(MarketingConsentResponse(
+ source=latest.source,
+ opted_in=latest.opted_in,
+ timestamp=latest.timestamp,
+ ))
+ return result
+
+
+ "/marketing-consent",
+ auth=JWTAuth(),
+ response=MarketingConsentResponse,
+ summary="Update marketing email consent",
+ description=(
+ "Record a marketing email consent decision for the authenticated user against a "
+ "source. Use `opted_in=false` to withdraw consent. Each call appends a new "
+ "timestamped record, preserving the full consent history. Requires a verified account."
+ ),
+ tags=["Marketing"],
+)
+def update_marketing_consent(request, body: MarketingConsentRequest):
+ check_email_verified(request)
+ _record_marketing_consent(request.user, body.source, body.opted_in)
+ return MarketingConsentResponse(
+ source=body.source,
+ opted_in=body.opted_in,
+ timestamp=timezone.now(),
+ )
+
+
+def _unsubscribe_from_token(token: str) -> None:
+ try:
+ data = signing.loads(token, salt=_UNSUBSCRIBE_SALT)
+ except signing.BadSignature:
+ raise InvalidRequest("Invalid or malformed unsubscribe token.", status=400)
+ user = MwmblUser.objects.filter(id=data["user_id"]).first()
+ if user is None:
+ raise InvalidRequest("Unknown user.", status=400)
+ _record_marketing_consent(user, data["source"], opted_in=False)
+
+
+ "/marketing/unsubscribe",
+ auth=None,
+ summary="One-click unsubscribe from marketing emails",
+ description=(
+ "RFC 8058 one-click unsubscribe target for the `List-Unsubscribe` email header. "
+ "Takes a signed `token` identifying the recipient and source — no login required. "
+ "Records an opt-out and is idempotent. Mail clients POST here with the body "
+ "`List-Unsubscribe=One-Click`."
+ ),
+ tags=["Marketing"],
+)
+def unsubscribe_marketing(request, token: str):
+ _unsubscribe_from_token(token)
+ return {"status": "ok", "message": "You have been unsubscribed from marketing emails."}
+
+
+ "/marketing/unsubscribe",
+ auth=None,
+ summary="One-click unsubscribe (browser-friendly)",
+ description=(
+ "Browser-friendly variant of the one-click unsubscribe endpoint, for users who open "
+ "the `List-Unsubscribe` link directly. Records the opt-out and returns a confirmation page."
+ ),
+ tags=["Marketing"],
+)
+def unsubscribe_marketing_page(request, token: str):
+ _unsubscribe_from_token(token)
+ return HttpResponse(
+ "<html><body><h1>You have been unsubscribed</h1>"
+ "<p>You will no longer receive marketing emails from Mwmbl.</p></body></html>",
+ content_type="text/html",
+ )
+
+
# ---------------------------------------------------------------------------
# API key management
# ---------------------------------------------------------------------------
diff --git a/mwmbl/platform/schemas.py b/mwmbl/platform/schemas.py
index d26a424..1302a23 100644
--- a/mwmbl/platform/schemas.py
+++ b/mwmbl/platform/schemas.py
@@ -2,7 +2,7 @@ from datetime import datetime
from typing import Optional, Literal
from ninja import Schema, ModelSchema, Field
-from mwmbl.models import AgreementType, DomainSubmission
+from mwmbl.models import AgreementType, DomainSubmission, MarketingSource
class UserProfileResponse(Schema):
@@ -100,6 +100,21 @@ class AgreementResponse(Schema):
accepted_at: datetime = Field(description="When the agreement was accepted.")
+# ---------------------------------------------------------------------------
+# Marketing consent
+# ---------------------------------------------------------------------------
+
+class MarketingConsentRequest(Schema):
+ source: MarketingSource = Field(description="The property the consent applies to (`GUI` or `API`).")
+ opted_in: bool = Field(description="True to opt in to marketing emails, False to withdraw consent.")
+
+
+class MarketingConsentResponse(Schema):
+ source: str = Field(description="The property the consent applies to.")
+ opted_in: bool = Field(description="The current opt-in state for this source.")
+ timestamp: datetime = Field(description="When this consent decision was recorded.")
+
+
class Registration(Schema):
email: str = Field(description="Email address for the new account. Must be unique.")
password: str = Field(description="Password for the new account.")
@@ -118,6 +133,21 @@ class Registration(Schema):
"Accepted values: `TERMS_OF_SERVICE_GUI`, `TERMS_OF_SERVICE_API`."
),
)
+ source: Optional[MarketingSource] = Field(
+ default=None,
+ description=(
+ "Which Mwmbl property the user signed up from (`GUI` = mwmbl.org, "
+ "`API` = developer.mwmbl.org). Determines the type of marketing email. "
+ "When provided, the marketing opt-in decision is recorded against this source."
+ ),
+ )
+ marketing_opt_in: bool = Field(
+ default=False,
+ description=(
+ "Whether the user opted in to marketing emails. Must reflect an affirmative, "
+ "unticked-by-default checkbox. Only recorded when `source` is also provided."
+ ),
+ )
class ConfirmEmail(Schema):
diff --git a/test/test_marketing_consent.py b/test/test_marketing_consent.py
new file mode 100644
index 0000000..9e68c83
--- /dev/null
+++ b/test/test_marketing_consent.py
@@ -0,0 +1,154 @@
+import json
+
+import pytest
+from allauth.account.models import EmailAddress
+from django.contrib.auth import get_user_model
+from ninja_jwt.tokens import RefreshToken
+
+from mwmbl.models import MarketingConsent, MarketingSource
+from mwmbl.platform.api import make_unsubscribe_token
+
+User = get_user_model()
+
+REGISTER_URL = "/api/v1/platform/register"
+CONSENT_URL = "/api/v1/platform/marketing-consent"
+UNSUBSCRIBE_URL = "/api/v1/platform/marketing/unsubscribe"
+
+
+def verified_user(db):
+ user = User.objects.create_user(
+ username="swift_falcon_379",
+ password="correctpassword",
+ )
+ EmailAddress.objects.create(
+ user=user, email="[email protected]", verified=True, primary=True
+ )
+ return user
+
+
+def access_token(verified_user):
+ return str(RefreshToken.for_user(verified_user).access_token)
+
+
+def _register(client, **extra):
+ body = {"email": "[email protected]", "password": "correctpassword"}
+ body.update(extra)
+ return client.post(REGISTER_URL, data=json.dumps(body), content_type="application/json")
+
+
+# ---------------------------------------------------------------------------
+# Registration records consent
+# ---------------------------------------------------------------------------
+
+def test_register_with_opt_in_records_consent(client):
+ response = _register(client, source="API", marketing_opt_in=True)
+ assert response.status_code == 200
+ user = User.objects.get(email="[email protected]")
+ consents = MarketingConsent.objects.filter(user=user)
+ assert consents.count() == 1
+ consent = consents.first()
+ assert consent.source == MarketingSource.API
+ assert consent.opted_in is True
+
+
+def test_register_with_decline_still_records(client):
+ response = _register(client, source="GUI", marketing_opt_in=False)
+ assert response.status_code == 200
+ user = User.objects.get(email="[email protected]")
+ consent = MarketingConsent.objects.get(user=user)
+ assert consent.source == MarketingSource.GUI
+ assert consent.opted_in is False
+
+
+def test_register_without_source_records_nothing(client):
+ response = _register(client, marketing_opt_in=True)
+ assert response.status_code == 200
+ user = User.objects.get(email="[email protected]")
+ assert MarketingConsent.objects.filter(user=user).count() == 0
+
+
+# ---------------------------------------------------------------------------
+# Authenticated view + update
+# ---------------------------------------------------------------------------
+
+def test_get_marketing_consent_returns_latest_per_source(client, verified_user, access_token):
+ MarketingConsent.objects.create(user=verified_user, source=MarketingSource.API, opted_in=True)
+ MarketingConsent.objects.create(user=verified_user, source=MarketingSource.API, opted_in=False)
+
+ response = client.get(CONSENT_URL, HTTP_AUTHORIZATION=f"Bearer {access_token}")
+ assert response.status_code == 200
+ data = response.json()
+ assert len(data) == 1
+ assert data[0]["source"] == "API"
+ assert data[0]["opted_in"] is False
+
+
+def test_update_marketing_consent_appends_row(client, verified_user, access_token):
+ MarketingConsent.objects.create(user=verified_user, source=MarketingSource.GUI, opted_in=True)
+
+ response = client.post(
+ CONSENT_URL,
+ data=json.dumps({"source": "GUI", "opted_in": False}),
+ content_type="application/json",
+ HTTP_AUTHORIZATION=f"Bearer {access_token}",
+ )
+ assert response.status_code == 200
+ assert response.json()["opted_in"] is False
+ # History preserved — row count grows rather than mutating in place.
+ assert MarketingConsent.objects.filter(user=verified_user, source=MarketingSource.GUI).count() == 2
+
+ # GET now reflects the withdrawal.
+ latest = client.get(CONSENT_URL, HTTP_AUTHORIZATION=f"Bearer {access_token}").json()
+ assert latest[0]["opted_in"] is False
+
+
+def test_marketing_consent_requires_auth(client):
+ assert client.get(CONSENT_URL).status_code == 401
+
+
+# ---------------------------------------------------------------------------
+# One-click unsubscribe (RFC 8058)
+# ---------------------------------------------------------------------------
+
+def test_unsubscribe_token_roundtrip_records_opt_out(client, verified_user):
+ token = make_unsubscribe_token(verified_user, MarketingSource.API)
+ response = client.post(f"{UNSUBSCRIBE_URL}?token={token}")
+ assert response.status_code == 200
+ consent = MarketingConsent.objects.get(user=verified_user, source=MarketingSource.API)
+ assert consent.opted_in is False
+
+
+def test_unsubscribe_is_idempotent(client, verified_user):
+ token = make_unsubscribe_token(verified_user, MarketingSource.GUI)
+ client.post(f"{UNSUBSCRIBE_URL}?token={token}")
+ client.post(f"{UNSUBSCRIBE_URL}?token={token}")
+ consents = MarketingConsent.objects.filter(user=verified_user, source=MarketingSource.GUI)
+ assert consents.count() == 2
+ assert all(c.opted_in is False for c in consents)
+
+
+def test_unsubscribe_rejects_bad_token(client, verified_user):
+ response = client.post(f"{UNSUBSCRIBE_URL}?token=garbage")
+ assert response.status_code == 400
+ assert MarketingConsent.objects.count() == 0
+
+
+def test_unsubscribe_get_renders_confirmation(client, verified_user):
+ token = make_unsubscribe_token(verified_user, MarketingSource.API)
+ response = client.get(f"{UNSUBSCRIBE_URL}?token={token}")
+ assert response.status_code == 200
+ assert b"unsubscribed" in response.content.lower()
+ assert MarketingConsent.objects.filter(user=verified_user).count() == 1