feat(api): account auth + unified premium entitlement

Add a REST account/auth surface and a source-aware premium entitlement that
honors legacy email subscriptions, replacing the email allow-list as the
premium source of truth.

Auth (user_management):
- DRF TokenAuthentication enabled globally (AllowAny default preserved); load
  user_management's REST surface without the allauth login wall
- POST /api/v3/auth/{register,login,me,logout} (email+password, no email verify)
- POST /api/v3/auth/social: server-side Apple/Google id-token verification via
  provider JWKS (PyJWT), find-or-link user by verified email

Billing:
- billing.Entitlement (tier/source/status/platform/current_period_end/features),
  admin-revocable via status; source tracks legacy_email | manual | revenuecat | stripe
- ensure_legacy_entitlement honors active legacy subs on every auth event
- resolve_entitlement (paid > manual > legacy) + manage_via routing
- GET /api/v3/billing/entitlement (auth required, fail-safe free)
- POST /api/v3/billing/webhooks/revenuecat reconcile seam (no client SDK yet)
- lowercase email in legacy verify + compat shim (case-sensitivity fix)

21 new tests pass (user_management + billing).

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: hc-sousa

src/billing/admin.py

@@ -1,6 +1,6 @@
 from django.contrib import admin
 
-from billing.models import Subscription
+from billing.models import Entitlement, Subscription
 
 
 @admin.register(Subscription)
@@ -10,3 +10,15 @@ class SubscriptionAdmin(admin.ModelAdmin):
     search_fields = ('email',)
     date_hierarchy = 'created_at'
     ordering = ('-created_at',)
+
+
+@admin.register(Entitlement)
+class EntitlementAdmin(admin.ModelAdmin):
+    # status is editable inline so staff can revoke legacy/manual premium quickly.
+    list_display = ('id', 'user', 'email', 'tier', 'source', 'status', 'current_period_end', 'updated_at')
+    list_editable = ('status',)
+    list_filter = ('tier', 'source', 'status', 'platform')
+    search_fields = ('email', 'user__email', 'user__username', 'external_id')
+    raw_id_fields = ('user',)
+    date_hierarchy = 'created_at'
+    ordering = ('-updated_at',)

src/billing/api_v3.py

@@ -0,0 +1,39 @@
+"""Billing v3 API: entitlement read + RevenueCat reconcile webhook (seam)."""
+
+from __future__ import annotations
+
+from django.conf import settings
+from django.views.decorators.csrf import csrf_exempt
+from rest_framework import status
+from rest_framework.decorators import api_view, permission_classes
+from rest_framework.permissions import AllowAny, IsAuthenticated
+from rest_framework.request import Request
+from rest_framework.response import Response
+
+from billing.services import entitlement_response, reconcile_revenuecat
+
+
+@api_view(['GET'])
+@permission_classes([IsAuthenticated])
+def entitlement_view(request: Request) -> Response:
+    return Response(entitlement_response(request.user))
+
+
+@api_view(['POST'])
+@permission_classes([AllowAny])
+@csrf_exempt
+def revenuecat_webhook(request: Request) -> Response:
+    """Future-IAP seam: reconcile RevenueCat events into Entitlement.
+
+    Authorized by a shared secret sent in the Authorization header (configured
+    in the RevenueCat dashboard). No client SDK is wired yet.
+    """
+    secret = getattr(settings, 'REVENUECAT_WEBHOOK_SECRET', '')
+    provided = request.headers.get('Authorization', '')
+    if not secret or provided != secret:
+        return Response({'error': 'unauthorized'}, status=status.HTTP_400_BAD_REQUEST)
+
+    body = request.data if isinstance(request.data, dict) else {}
+    event = body.get('event') or {}
+    reconcile_revenuecat(event)
+    return Response({'status': 'ok'})

src/billing/migrations/0002_entitlement_entitlement_uniq_entitlement_user_source.py

@@ -0,0 +1,114 @@
+# Generated by Django 5.0.6 on 2026-06-04 17:15
+
+import billing.models
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("billing", "0001_initial"),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="Entitlement",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("email", models.EmailField(blank=True, db_index=True, max_length=254)),
+                (
+                    "tier",
+                    models.CharField(
+                        choices=[("free", "Free"), ("premium", "Premium")],
+                        default="premium",
+                        max_length=16,
+                    ),
+                ),
+                (
+                    "source",
+                    models.CharField(
+                        choices=[
+                            ("legacy_email", "Legacy email allow-list"),
+                            ("manual", "Manual grant"),
+                            ("revenuecat", "RevenueCat (IAP)"),
+                            ("stripe", "Stripe"),
+                        ],
+                        max_length=20,
+                    ),
+                ),
+                (
+                    "status",
+                    models.CharField(
+                        choices=[
+                            ("active", "Active"),
+                            ("canceled", "Canceled"),
+                            ("expired", "Expired"),
+                        ],
+                        default="active",
+                        max_length=16,
+                    ),
+                ),
+                (
+                    "platform",
+                    models.CharField(
+                        blank=True,
+                        choices=[
+                            ("ios", "iOS"),
+                            ("android", "Android"),
+                            ("web", "Web"),
+                        ],
+                        max_length=10,
+                    ),
+                ),
+                ("external_id", models.CharField(blank=True, max_length=255)),
+                ("current_period_end", models.DateTimeField(blank=True, null=True)),
+                ("features", models.JSONField(default=billing.models.default_features)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                (
+                    "user",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="entitlements",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "db_table": "billing_entitlement",
+                "indexes": [
+                    models.Index(
+                        fields=["user", "status"], name="billing_ent_user_id_a06777_idx"
+                    ),
+                    models.Index(
+                        fields=["email", "status"], name="billing_ent_email_29a145_idx"
+                    ),
+                    models.Index(
+                        fields=["source", "status"],
+                        name="billing_ent_source_1376df_idx",
+                    ),
+                ],
+            },
+        ),
+        migrations.AddConstraint(
+            model_name="entitlement",
+            constraint=models.UniqueConstraint(
+                condition=models.Q(("user__isnull", False)),
+                fields=("user", "source"),
+                name="uniq_entitlement_user_source",
+            ),
+        ),
+    ]

src/billing/models.py

@@ -1,9 +1,19 @@
-"""Legacy email subscription allow-list (compat with old subscriptions app)."""
+"""Billing models.
 
+``Subscription`` is the legacy email allow-list (compat with the old
+subscriptions app). ``Entitlement`` is the unified, source-aware source of
+truth for premium across legacy, manual grants, and (future) RevenueCat/Stripe.
+"""
+
+from django.conf import settings
 from django.core.validators import EmailValidator
 from django.db import models
 
 
+def default_features() -> list:
+    return ['ad_removal']
+
+
 class Subscription(models.Model):
     id = models.AutoField(primary_key=True)
     email = models.EmailField(validators=[EmailValidator()], unique=True)
@@ -22,3 +32,74 @@ class Meta:
     def __str__(self) -> str:
         status = 'Active' if self.is_active else 'Inactive'
         return f'{self.email} - {status}'
+
+
+class Entitlement(models.Model):
+    """Unified premium entitlement — one row per (user/email, source)."""
+
+    TIER_FREE = 'free'
+    TIER_PREMIUM = 'premium'
+    TIER_CHOICES = [(TIER_FREE, 'Free'), (TIER_PREMIUM, 'Premium')]
+
+    SOURCE_LEGACY = 'legacy_email'
+    SOURCE_MANUAL = 'manual'
+    SOURCE_REVENUECAT = 'revenuecat'
+    SOURCE_STRIPE = 'stripe'
+    SOURCE_CHOICES = [
+        (SOURCE_LEGACY, 'Legacy email allow-list'),
+        (SOURCE_MANUAL, 'Manual grant'),
+        (SOURCE_REVENUECAT, 'RevenueCat (IAP)'),
+        (SOURCE_STRIPE, 'Stripe'),
+    ]
+
+    STATUS_ACTIVE = 'active'
+    STATUS_CANCELED = 'canceled'
+    STATUS_EXPIRED = 'expired'
+    STATUS_CHOICES = [
+        (STATUS_ACTIVE, 'Active'),
+        (STATUS_CANCELED, 'Canceled'),
+        (STATUS_EXPIRED, 'Expired'),
+    ]
+
+    PLATFORM_CHOICES = [('ios', 'iOS'), ('android', 'Android'), ('web', 'Web')]
+
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name='entitlements',
+        null=True,
+        blank=True,
+    )
+    email = models.EmailField(blank=True, db_index=True)
+    tier = models.CharField(max_length=16, choices=TIER_CHOICES, default=TIER_PREMIUM)
+    source = models.CharField(max_length=20, choices=SOURCE_CHOICES)
+    status = models.CharField(max_length=16, choices=STATUS_CHOICES, default=STATUS_ACTIVE)
+    platform = models.CharField(max_length=10, choices=PLATFORM_CHOICES, blank=True)
+    external_id = models.CharField(max_length=255, blank=True)
+    current_period_end = models.DateTimeField(null=True, blank=True)
+    features = models.JSONField(default=default_features)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        db_table = 'billing_entitlement'
+        constraints = [
+            models.UniqueConstraint(
+                fields=['user', 'source'],
+                name='uniq_entitlement_user_source',
+                condition=models.Q(user__isnull=False),
+            ),
+        ]
+        indexes = [
+            models.Index(fields=['user', 'status']),
+            models.Index(fields=['email', 'status']),
+            models.Index(fields=['source', 'status']),
+        ]
+
+    def __str__(self) -> str:
+        who = self.user_id or self.email or 'unlinked'
+        return f'{who} - {self.tier}/{self.source} ({self.status})'
+
+    @property
+    def is_active(self) -> bool:
+        return self.status == self.STATUS_ACTIVE and self.tier == self.TIER_PREMIUM