Epic 5 Complete: Billing, Subscriptions, and Admin Features

Resolve all 5 deferred items from Epic 5 adversarial code review:
- Migration 124: Add CASCADE to subscriptionstatus enum drop (prevent orphaned references)
- Stripe rate limiting: In-memory per-user limiter (20 calls/60s) on verify-checkout-session
- Subscription request cooldown: 24h cooldown before resubmitting rejected requests
- Token reset date: Initialize on first subscription activation
- Checkout URL validation: Confirmed HTTPS-only (Stripe always returns HTTPS)

Implement Story 5.4 (Usage Tracking & Rate Limit Enforcement):
- Page quota pre-check at HTTP upload layer
- Extend UserRead schema with token quota fields
- Frontend 402 error handling in document upload
- Quota indicator in dashboard sidebar

Story 5.5 (Admin Seed & Approval Flow):
- Seed admin user migration with default credentials warning
- Subscription approval/rejection routes with admin guard
- 24h rejection cooldown enforcement

Story 5.6 (Admin-Only Model Config):
- Global model config visible across all search spaces
- Per-search-space model configs with user access control
- Superuser CRUD for global configs

Additional fixes from code review:
- PageLimitService: PAST_DUE subscriptions enforce free-tier limits
- TokenQuotaService: PAST_DUE subscriptions enforce free-tier limits
- Config routes: Fixed user_id.is_(None) filter on mutation endpoints
- Stripe webhook: Added guard against silent plan downgrade on unrecognized price_id

All changes formatted with Ruff (Python) and Biome (TypeScript).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

surfsense_backend/app/schemas/image_generation.py

@@ -55,8 +55,9 @@ class ImageGenerationConfigBase(BaseModel):
 class ImageGenerationConfigCreate(ImageGenerationConfigBase):
     """Schema for creating a new ImageGenerationConfig."""
 
-    search_space_id: int = Field(
-        ..., description="Search space ID to associate the config with"
+    search_space_id: int | None = Field(
+        None,
+        description="Search space ID. None = global admin config visible to all spaces",
     )
 
 
@@ -79,8 +80,8 @@ class ImageGenerationConfigRead(ImageGenerationConfigBase):
 
     id: int
     created_at: datetime
-    search_space_id: int
-    user_id: uuid.UUID
+    search_space_id: int | None = None
+    user_id: uuid.UUID | None = None
 
     model_config = ConfigDict(from_attributes=True)
 
@@ -98,8 +99,8 @@ class ImageGenerationConfigPublic(BaseModel):
     api_version: str | None = None
     litellm_params: dict[str, Any] | None = None
     created_at: datetime
-    search_space_id: int
-    user_id: uuid.UUID
+    search_space_id: int | None = None
+    user_id: uuid.UUID | None = None
 
     model_config = ConfigDict(from_attributes=True)
 

surfsense_backend/app/schemas/new_llm_config.py

@@ -60,8 +60,9 @@ class NewLLMConfigBase(BaseModel):
 class NewLLMConfigCreate(NewLLMConfigBase):
     """Schema for creating a new NewLLMConfig."""
 
-    search_space_id: int = Field(
-        ..., description="Search space ID to associate the config with"
+    search_space_id: int | None = Field(
+        None,
+        description="Search space ID. None = global admin config visible to all spaces",
     )
 
 
@@ -90,8 +91,8 @@ class NewLLMConfigRead(NewLLMConfigBase):
 
     id: int
     created_at: datetime
-    search_space_id: int
-    user_id: uuid.UUID
+    search_space_id: int | None = None
+    user_id: uuid.UUID | None = None
 
     model_config = ConfigDict(from_attributes=True)
 
@@ -119,8 +120,8 @@ class NewLLMConfigPublic(BaseModel):
     citations_enabled: bool
 
     created_at: datetime
-    search_space_id: int
-    user_id: uuid.UUID
+    search_space_id: int | None = None
+    user_id: uuid.UUID | None = None
 
     model_config = ConfigDict(from_attributes=True)
 

surfsense_backend/app/schemas/stripe.py

@@ -33,6 +33,7 @@ class CreateSubscriptionCheckoutResponse(BaseModel):
     """Response containing the Stripe-hosted subscription checkout URL."""
 
     checkout_url: str
+    admin_approval_mode: bool = False
 
 
 class CreateCheckoutSessionResponse(BaseModel):

surfsense_backend/app/schemas/users.py

@@ -6,6 +6,10 @@ from fastapi_users import schemas
 class UserRead(schemas.BaseUser[uuid.UUID]):
     pages_limit: int
     pages_used: int
+    monthly_token_limit: int
+    tokens_used_this_month: int
+    plan_id: str
+    subscription_status: str
     display_name: str | None = None
     avatar_url: str | None = None
 

surfsense_backend/app/schemas/vision_llm.py

@@ -20,7 +20,10 @@ class VisionLLMConfigBase(BaseModel):
 
 
 class VisionLLMConfigCreate(VisionLLMConfigBase):
-    search_space_id: int = Field(...)
+    search_space_id: int | None = Field(
+        None,
+        description="Search space ID. None = global admin config visible to all spaces",
+    )
 
 
 class VisionLLMConfigUpdate(BaseModel):
@@ -38,8 +41,8 @@ class VisionLLMConfigUpdate(BaseModel):
 class VisionLLMConfigRead(VisionLLMConfigBase):
     id: int
     created_at: datetime
-    search_space_id: int
-    user_id: uuid.UUID
+    search_space_id: int | None = None
+    user_id: uuid.UUID | None = None
 
     model_config = ConfigDict(from_attributes=True)
 
@@ -55,8 +58,8 @@ class VisionLLMConfigPublic(BaseModel):
     api_version: str | None = None
     litellm_params: dict[str, Any] | None = None
     created_at: datetime
-    search_space_id: int
-    user_id: uuid.UUID
+    search_space_id: int | None = None
+    user_id: uuid.UUID | None = None
 
     model_config = ConfigDict(from_attributes=True)