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/db.py

@@ -1197,15 +1197,15 @@ class ImageGenerationConfig(BaseModel, TimestampMixin):
 
     # Relationships
     search_space_id = Column(
-        Integer, ForeignKey("searchspaces.id", ondelete="CASCADE"), nullable=False
+        Integer, ForeignKey("searchspaces.id", ondelete="CASCADE"), nullable=True
     )
     search_space = relationship(
         "SearchSpace", back_populates="image_generation_configs"
     )
 
-    # User who created this config
+    # User who created this config (NULL for admin-created global configs)
     user_id = Column(
-        UUID(as_uuid=True), ForeignKey("user.id", ondelete="CASCADE"), nullable=False
+        UUID(as_uuid=True), ForeignKey("user.id", ondelete="CASCADE"), nullable=True
     )
     user = relationship("User", back_populates="image_generation_configs")
 
@@ -1227,12 +1227,13 @@ class VisionLLMConfig(BaseModel, TimestampMixin):
     litellm_params = Column(JSON, nullable=True, default={})
 
     search_space_id = Column(
-        Integer, ForeignKey("searchspaces.id", ondelete="CASCADE"), nullable=False
+        Integer, ForeignKey("searchspaces.id", ondelete="CASCADE"), nullable=True
     )
     search_space = relationship("SearchSpace", back_populates="vision_llm_configs")
 
+    # User who created this config (NULL for admin-created global configs)
     user_id = Column(
-        UUID(as_uuid=True), ForeignKey("user.id", ondelete="CASCADE"), nullable=False
+        UUID(as_uuid=True), ForeignKey("user.id", ondelete="CASCADE"), nullable=True
     )
     user = relationship("User", back_populates="vision_llm_configs")
 
@@ -1535,13 +1536,13 @@ class NewLLMConfig(BaseModel, TimestampMixin):
 
     # === Relationships ===
     search_space_id = Column(
-        Integer, ForeignKey("searchspaces.id", ondelete="CASCADE"), nullable=False
+        Integer, ForeignKey("searchspaces.id", ondelete="CASCADE"), nullable=True
     )
     search_space = relationship("SearchSpace", back_populates="new_llm_configs")
 
-    # User who created this config
+    # User who created this config (NULL for admin-created global configs)
     user_id = Column(
-        UUID(as_uuid=True), ForeignKey("user.id", ondelete="CASCADE"), nullable=False
+        UUID(as_uuid=True), ForeignKey("user.id", ondelete="CASCADE"), nullable=True
     )
     user = relationship("User", back_populates="new_llm_configs")
 
@@ -1683,6 +1684,56 @@ class PagePurchase(Base, TimestampMixin):
     user = relationship("User", back_populates="page_purchases")
 
 
+class SubscriptionRequestStatus(StrEnum):
+    PENDING = "pending"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+
+
+class SubscriptionRequest(Base):
+    """Tracks subscription upgrade requests when Stripe is not configured (admin-approval flow)."""
+
+    __tablename__ = "subscription_requests"
+    __allow_unmapped__ = True
+
+    id = Column(
+        UUID(as_uuid=True),
+        primary_key=True,
+        server_default=text("gen_random_uuid()"),
+    )
+    user_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("user.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    plan_id = Column(String(50), nullable=False)
+    status = Column(
+        SQLAlchemyEnum(
+            SubscriptionRequestStatus,
+            name="subscriptionrequeststatus",
+            create_type=False,
+            values_callable=lambda x: [e.value for e in x],
+        ),
+        nullable=False,
+        default=SubscriptionRequestStatus.PENDING,
+        server_default="pending",
+    )
+    created_at = Column(
+        TIMESTAMP(timezone=True),
+        nullable=False,
+        server_default=text("now()"),
+    )
+    approved_at = Column(TIMESTAMP(timezone=True), nullable=True)
+    approved_by = Column(
+        UUID(as_uuid=True),
+        ForeignKey("user.id"),
+        nullable=True,
+    )
+
+    user = relationship("User", foreign_keys=[user_id], back_populates="subscription_requests")
+
+
 class SearchSpaceRole(BaseModel, TimestampMixin):
     """
     Custom roles that can be defined per search space.
@@ -1953,6 +2004,12 @@ if config.AUTH_TYPE == "GOOGLE":
             back_populates="user",
             cascade="all, delete-orphan",
         )
+        subscription_requests = relationship(
+            "SubscriptionRequest",
+            foreign_keys="SubscriptionRequest.user_id",
+            back_populates="user",
+            cascade="all, delete-orphan",
+        )
 
         # Page usage tracking for ETL services
         pages_limit = Column(
@@ -1968,7 +2025,7 @@ if config.AUTH_TYPE == "GOOGLE":
         tokens_used_this_month = Column(Integer, nullable=False, default=0, server_default="0")
         token_reset_date = Column(Date, nullable=True)
         subscription_status = Column(
-            SQLAlchemyEnum(SubscriptionStatus, name="subscriptionstatus", create_type=True),
+            SQLAlchemyEnum(SubscriptionStatus, name="subscriptionstatus", create_type=True, values_callable=lambda x: [e.value for e in x]),
             nullable=False,
             default=SubscriptionStatus.FREE,
             server_default="free",
@@ -2082,6 +2139,12 @@ else:
             back_populates="user",
             cascade="all, delete-orphan",
         )
+        subscription_requests = relationship(
+            "SubscriptionRequest",
+            foreign_keys="SubscriptionRequest.user_id",
+            back_populates="user",
+            cascade="all, delete-orphan",
+        )
 
         # Page usage tracking for ETL services
         pages_limit = Column(
@@ -2097,7 +2160,7 @@ else:
         tokens_used_this_month = Column(Integer, nullable=False, default=0, server_default="0")
         token_reset_date = Column(Date, nullable=True)
         subscription_status = Column(
-            SQLAlchemyEnum(SubscriptionStatus, name="subscriptionstatus", create_type=True),
+            SQLAlchemyEnum(SubscriptionStatus, name="subscriptionstatus", create_type=True, values_callable=lambda x: [e.value for e in x]),
             nullable=False,
             default=SubscriptionStatus.FREE,
             server_default="free",