Files
karaoke-gen/backend/services/user_service.py
T
Andrew Beveridge ☄️andClaude Opus 5.5 c277bc8ee3 feat: local E2E stack (fake workers + test API) + email-code sign-in (v0.275.0) (#1165)
## Summary
- **Local stack:** `scripts/local-stack.sh up --frontend` runs the
**real** backend on the Firestore + GCS emulators with `FAKE_WORKERS=1`.
In-process fake workers move jobs through their real states in seconds,
using tiny real media, so web Playwright and mobile Maestro full-journey
tests can run offline against the same endpoints.
- **Email-code sign-in** (nomad-mobile spec §4.1): `POST
/api/users/auth/send-code` + `verify-code`. The code logic is shared
with kjbox via `LoginCodeStore`, and sends are throttled per email and
per IP.
- **Bug fix found by the new suite:** `confirm-duration` moved jobs to
`separating_stage1`, from which they can never reach review. It now
resumes at `downloading`. No prod job had taken this path yet.

## Changes
- `backend/services/fake_workers/`: dispatch seam in
`WorkerService.trigger_*`, plus fake search, download, checkout and
outbox, scenarios, and per-user config. The real stem upload, transcode,
backing-vocals analysis and preview render are reused. Every check is
strict (`is True`), so a MagicMock settings object never enables the
fakes, and startup **refuses FAKE_WORKERS in production**.
- `/api/test/*` router (mounted only in that mode): `status`,
`scenario`, `fake-config`, `emails`, `reset`, plus the fake Stripe
checkout page. Paying it runs the real webhook handler.
- `frontend/e2e/local-stack/` (9 specs, ~50s):
  - sign-up → make → review → instrumental → download
  - buy and cancel credits
  - duration confirm, failed, complete and review states
  - code sign-in and lockout
- New required CI job `local-stack-e2e`.
- Docs: TESTING.md § Local stack, DEVELOPMENT.md, API.md, README,
LESSONS-LEARNED.
- `MAX_SIGNUPS_PER_IP` can now be set by env. Only the local stack
raises it; production keeps the default of 2.

## Testing
- [x] Backend unit: 6175 passed
- [x] Emulator: 152 passed
- [x] Frontend Jest: 1706 passed
- [x] Local-stack Playwright: 9/9 passed (CI mode)

## Review
- [x] CodeRabbit CLI review completed locally. 1 minor finding declined:
it suggested swallowing infrastructure errors in send-code as fake
"sent" responses, which would hide real outages from users.

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01AGuxtgoscF6RJGtpjHPg3W

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-15 16:00:24 -04:00

1447 lines
56 KiB
Python

"""
User service for authentication, credits, and user management.
Handles:
- Magic link authentication (send, verify)
- Session management
- Credit operations (add, deduct, refund)
- User CRUD operations
"""
import logging
import os
import secrets
import uuid
from datetime import datetime, timedelta, timezone
from typing import Dict, Optional, List, Tuple
from google.api_core import exceptions as google_exceptions
from google.cloud import firestore
from google.cloud.firestore_v1 import FieldFilter
from google.cloud.firestore_v1 import Increment
from backend.utils.keyed_lock import user_lock
from backend.config import get_settings
from backend.models.user import (
User,
UserRole,
UserPublic,
MagicLinkToken,
Session,
CreditTransaction,
)
logger = logging.getLogger(__name__)
def _safe_positive_int_env(name: str, default: int) -> int:
"""Parse a positive-int env var, falling back to default on empty/invalid/<=0.
Used for BOARD_MAX_SIGNUPS_PER_IP — a bad value must not crash import or (if 0/
negative) rate-limit every signup.
"""
try:
value = int(os.getenv(name, str(default)))
except (TypeError, ValueError):
return default
return value if value > 0 else default
# Collection names
USERS_COLLECTION = "gen_users"
MAGIC_LINKS_COLLECTION = "magic_links"
SESSIONS_COLLECTION = "sessions"
PROCESSED_STRIPE_SESSIONS_COLLECTION = "processed_stripe_sessions"
# Token/session configuration
MAGIC_LINK_EXPIRY_MINUTES = 24 * 60 # 24h — buffer for slow email delivery (Yahoo can defer for hours)
SESSION_EXPIRY_DAYS = 7
SESSION_ABSOLUTE_EXPIRY_DAYS = 30
MAX_CREDIT_TRANSACTIONS = 100 # Keep last N transactions
class UserService:
"""Service for user management and authentication."""
# Number of free credits granted to new users
NEW_USER_FREE_CREDITS = 1
def __init__(self):
"""Initialize user service with Firestore client."""
self.settings = get_settings()
self.db = firestore.Client(project=self.settings.google_cloud_project)
# =========================================================================
# User CRUD Operations
# =========================================================================
def get_user_doc_ref(self, email: str):
"""Get the Firestore document reference for a user by email.
Handles both email-keyed docs (doc ID = email) and hash-keyed docs
(doc ID = hash, email stored as field). Returns None if not found.
"""
try:
# First try direct lookup by email as doc ID
doc_ref = self.db.collection(USERS_COLLECTION).document(email.lower())
doc = doc_ref.get()
if doc.exists:
return doc_ref
# Fallback: query by email field (for hash-keyed docs)
query = self.db.collection(USERS_COLLECTION).where(
filter=FieldFilter('email', '==', email.lower())
).limit(1)
results = list(query.stream())
if results:
return results[0].reference
return None
except Exception:
logger.exception(f"Error finding user doc ref for {email}")
return None
def get_user(self, email: str) -> Optional[User]:
"""Get a user by email."""
try:
doc_ref = self.db.collection(USERS_COLLECTION).document(email.lower())
doc = doc_ref.get()
if doc.exists:
return User(**doc.to_dict())
# Fallback: query by email field (for hash-keyed docs)
query = self.db.collection(USERS_COLLECTION).where(
filter=FieldFilter('email', '==', email.lower())
).limit(1)
results = list(query.stream())
if results:
return User(**results[0].to_dict())
return None
except Exception:
logger.exception(f"Error getting user {email}")
return None
def get_or_create_user(
self,
email: str,
tenant_id: Optional[str] = None,
signup_ip: Optional[str] = None,
device_fingerprint: Optional[str] = None,
signup_source: Optional[str] = None,
signup_venue: Optional[str] = None,
signup_attribution: Optional[Dict[str, str]] = None,
) -> User:
"""
Get existing user or create a new one.
Welcome credits are granted on first magic link verification, not here.
Args:
email: User's email address
tenant_id: Tenant ID for white-label portals (None = default Nomad Karaoke)
signup_ip: Client IP address at signup (for rate limiting)
device_fingerprint: Browser fingerprint at signup (for rate limiting)
signup_source: Acquisition channel for partner signups (e.g. "kjbox");
only recorded when the user is created here
signup_venue: Partner-reported venue for the signup (kjbox)
signup_attribution: Cleaned first-touch UTM/referrer attribution
(see signup_attribution.clean_attribution); only recorded when
the user is created here
Note: If user exists but has a different tenant_id, the existing user is returned.
Users are uniquely identified by email, not email+tenant.
"""
email = email.lower()
user = self.get_user(email)
if user:
# If user exists but tenant_id differs, we still return the user
# This allows users to access multiple tenants with one account
# (though features may be restricted per-tenant)
return user
# Create new user with zero credits (welcome credits granted on first verification)
user = User(
email=email,
credits=0,
credit_transactions=[],
tenant_id=tenant_id, # Associate with tenant on creation
signup_ip=signup_ip,
device_fingerprint=device_fingerprint,
signup_source=signup_source,
signup_venue=signup_venue,
signup_attribution=signup_attribution,
)
self._save_user(user)
logger.info(f"Created new user: {email} (tenant: {tenant_id or 'default'}) — credits pending verification")
return user
def _save_user(self, user: User) -> None:
"""Save user to Firestore."""
try:
user.updated_at = datetime.utcnow()
doc_ref = self.db.collection(USERS_COLLECTION).document(user.email.lower())
doc_ref.set(user.model_dump(mode='json'))
except Exception:
logger.exception(f"Error saving user {user.email}")
raise
def update_user(self, email: str, **updates) -> Optional[User]:
"""Update user fields."""
try:
updates['updated_at'] = datetime.utcnow()
doc_ref = self.get_user_doc_ref(email)
if not doc_ref:
logger.warning(f"Cannot update user {email}: doc not found")
return None
doc_ref.update(updates)
return self.get_user(email)
except Exception:
logger.exception(f"Error updating user {email}")
return None
def list_users(self, limit: int = 100, include_inactive: bool = False) -> List[User]:
"""List all users (admin only)."""
try:
query = self.db.collection(USERS_COLLECTION)
if not include_inactive:
query = query.where(filter=FieldFilter('is_active', '==', True))
query = query.order_by('created_at', direction=firestore.Query.DESCENDING)
query = query.limit(limit)
docs = query.stream()
return [User(**doc.to_dict()) for doc in docs]
except Exception:
logger.exception("Error listing users")
return []
def get_user_public(self, email: str) -> Optional[UserPublic]:
"""Get public user info."""
user = self.get_user(email)
if not user:
return None
return UserPublic(
email=user.email,
role=user.role,
credits=user.credits,
display_name=user.display_name,
total_jobs_created=user.total_jobs_created,
total_jobs_completed=user.total_jobs_completed,
tenant_id=user.tenant_id,
)
# =========================================================================
# Magic Link Authentication
# =========================================================================
def create_magic_link(
self,
email: str,
ip_address: Optional[str] = None,
user_agent: Optional[str] = None,
tenant_id: Optional[str] = None,
device_fingerprint: Optional[str] = None,
referral_code: Optional[str] = None,
purpose: Optional[str] = None,
attribution: Optional[Dict[str, object]] = None,
) -> MagicLinkToken:
"""
Create a magic link token for email authentication.
Returns the token object. The actual sending of the email
should be handled by the caller (or an email service).
Args:
email: User's email address
ip_address: Client IP for auditing
user_agent: Client user agent for auditing
tenant_id: Tenant ID for white-label portals (None = default Nomad Karaoke)
device_fingerprint: Browser fingerprint for anti-abuse
attribution: Raw client-supplied first-touch UTM/referrer data; cleaned
and stored only if this call creates the user
"""
from backend.services.signup_attribution import clean_attribution, derive_signup_source
email = email.lower()
try:
signup_attribution = clean_attribution(attribution)
except Exception: # attribution is best-effort and must never block sign-in
logger.warning("Ignoring unparseable signup attribution", exc_info=True)
signup_attribution = None
# Ensure user exists (with tenant association, signup IP, fingerprint and
# first-touch attribution — the latter two only matter on creation)
self.get_or_create_user(
email,
tenant_id=tenant_id,
signup_ip=ip_address,
device_fingerprint=device_fingerprint,
signup_source=derive_signup_source(signup_attribution),
signup_attribution=signup_attribution,
)
# Generate secure token
token = secrets.token_urlsafe(32)
magic_link = MagicLinkToken(
token=token,
email=email,
expires_at=datetime.utcnow() + timedelta(minutes=MAGIC_LINK_EXPIRY_MINUTES),
ip_address=ip_address,
user_agent=user_agent,
tenant_id=tenant_id,
device_fingerprint=device_fingerprint,
referral_code=referral_code,
purpose=purpose,
)
# Save to Firestore
doc_ref = self.db.collection(MAGIC_LINKS_COLLECTION).document(token)
doc_ref.set(magic_link.model_dump(mode='json'))
logger.info(f"Created magic link for {email}")
return magic_link
def create_admin_login_token(
self,
email: str,
expiry_hours: int = 24,
purpose: Optional[str] = None,
) -> MagicLinkToken:
"""
Create an admin login token for email-embedded authentication links.
Similar to magic links but with configurable expiry (default 24 hours).
Used for made-for-you order notification emails to allow admin one-click login.
Args:
email: Admin's email address to authenticate as
expiry_hours: Hours until token expires (default: 24, max: 168)
purpose: Optional purpose tag (e.g. "job_review:<job_id>") — the
verify endpoint maps known purposes to a post-login redirect
Returns:
MagicLinkToken object containing the token
Raises:
ValueError: If expiry_hours is out of valid range (1-168)
"""
# Validate expiry_hours (1 hour to 7 days)
if not 1 <= expiry_hours <= 168:
raise ValueError(f"expiry_hours must be between 1 and 168, got {expiry_hours}")
email = email.lower()
# Ensure user exists
self.get_or_create_user(email)
# Generate secure token
token = secrets.token_urlsafe(32)
admin_login = MagicLinkToken(
token=token,
email=email,
expires_at=datetime.utcnow() + timedelta(hours=expiry_hours),
purpose=purpose,
)
# Save to Firestore (same collection as magic links for unified verification)
doc_ref = self.db.collection(MAGIC_LINKS_COLLECTION).document(token)
doc_ref.set(admin_login.model_dump(mode='json'))
# Log with redacted email (show only domain) for PII protection
domain = email.split('@')[-1] if '@' in email else 'unknown'
logger.info(f"Created admin login token for ***@{domain} (expires in {expiry_hours}h)")
return admin_login
def verify_magic_link(self, token: str) -> Tuple[bool, Optional[User], str]:
"""
Verify a magic link token using a Firestore transaction to prevent race conditions.
Returns:
(success, user, message)
"""
try:
doc_ref = self.db.collection(MAGIC_LINKS_COLLECTION).document(token)
@firestore.transactional
def verify_in_transaction(transaction):
"""Atomically verify and mark magic link as used."""
doc = doc_ref.get(transaction=transaction)
if not doc.exists:
return False, None, "Invalid or expired link"
magic_link = MagicLinkToken(**doc.to_dict())
# Check if already used
if magic_link.used:
return False, None, "This link has already been used"
# Check expiry
if datetime.utcnow() > magic_link.expires_at:
return False, None, "This link has expired"
# Mark as used atomically within transaction
transaction.update(doc_ref, {
'used': True,
'used_at': datetime.utcnow()
})
return True, magic_link.email, "Success"
# Execute the transaction
transaction = self.db.transaction()
success, email_or_error, message = verify_in_transaction(transaction)
if not success:
return False, None, message
# Get user and mark email as verified (outside transaction)
user = self.get_user(email_or_error)
if user:
self.update_user(
email_or_error,
email_verified=True,
last_login_at=datetime.utcnow()
)
user = self.get_user(email_or_error) # Refresh
logger.info(f"Magic link verified for {email_or_error}")
return True, user, "Successfully authenticated"
except Exception:
logger.exception("Error verifying magic link")
return False, None, "An error occurred during verification"
def get_magic_link_status(self, token: str) -> str:
"""
Read-only check of a magic link's status WITHOUT consuming it.
Used by the verify page on load to decide whether to show the
"Complete Sign-In" gate (valid) or a dead-link message (used/expired).
Crucially this must never mutate the token: an email link-scanner that
renders the verify page triggers this read, but must not burn a still-
valid link before the real user clicks.
Returns one of: "valid", "used", "expired", "invalid".
"""
try:
if not token or not token.strip():
return "invalid"
doc = self.db.collection(MAGIC_LINKS_COLLECTION).document(token).get()
if not doc.exists:
return "invalid"
magic_link = MagicLinkToken(**doc.to_dict())
if magic_link.used:
return "used"
if datetime.utcnow() > magic_link.expires_at:
return "expired"
return "valid"
except Exception:
logger.exception("Error checking magic link status")
return "invalid"
def grant_welcome_credits_if_eligible(
self,
email: str,
precomputed_eval: Optional[dict] = None,
) -> Tuple[bool, str]:
"""
Grant welcome credits on first magic link verification.
Uses AI evaluation to check for abuse before granting. Fail-open:
if evaluation fails, credits are granted anyway.
Uses a dedicated welcome_credits_granted flag as primary idempotency
check (survives credit_transactions list trimming). Falls back to
checking for welcome_credit transaction as secondary defense.
Args:
email: User's email address.
precomputed_eval: Optional pre-computed evaluation from magic link doc.
Keys: credit_eval_decision, credit_eval_reasoning, credit_eval_error.
If provided and has a decision, skips the AI call.
Returns:
Tuple of (credits_granted: bool, status: str).
status is one of: "granted", "denied", "already_granted", "not_found", "error"
"""
try:
email = email.lower()
user = self.get_user(email)
if not user:
return False, "not_found"
# Primary check: dedicated flag (survives transaction list trimming)
if user.welcome_credits_granted:
return False, "already_granted"
# Secondary check: look for existing welcome_credit transaction
for txn in user.credit_transactions:
if txn.reason == "welcome_credit":
return False, "already_granted"
# Skip AI evaluation for test emails (e.g. E2E test accounts)
# to avoid wasting LLM credits and sending unnecessary denial emails
from backend.utils.test_data import is_test_email
if not is_test_email(email):
# AI evaluation: check for abuse signals before granting
# Use pre-computed result from magic link if available
try:
from backend.services.credit_evaluation_service import (
get_credit_evaluation_service,
CreditEvaluation,
)
precomputed_decision = (precomputed_eval or {}).get("credit_eval_decision")
if precomputed_decision:
logger.info(f"Using pre-computed credit eval for {email}: {precomputed_decision}")
evaluation = CreditEvaluation(
decision=precomputed_decision,
reasoning=(precomputed_eval or {}).get("credit_eval_reasoning", ""),
confidence=1.0,
error=(precomputed_eval or {}).get("credit_eval_error"),
)
else:
eval_service = get_credit_evaluation_service()
evaluation = eval_service.evaluate(email, "welcome")
if evaluation.decision == "deny":
# Mark as evaluated but not granted so we don't re-evaluate
self.update_user(email, welcome_credits_granted=True)
logger.info(
f"Denied welcome credits to {email}: {evaluation.reasoning}"
)
try:
from backend.services.email_service import get_email_service
get_email_service().send_credit_denied_email(email, "welcome")
except Exception:
logger.exception(f"Failed to send credit denied email to {email}")
return False, "denied"
if evaluation.decision == "pending_review":
# Don't mark welcome_credits_granted — allow retry after manual review
logger.info(
f"Welcome credits pending review for {email}: {evaluation.reasoning}"
)
try:
from backend.services.email_service import get_email_service
email_service = get_email_service()
email_service.send_credit_review_needed_email(
email, "welcome", evaluation.reasoning, signals=evaluation.signals,
)
except Exception:
logger.exception(f"Failed to send review needed email for {email}")
return False, "pending_review"
except Exception:
logger.exception(f"Credit evaluation failed for {email} — pending review (fail-closed)")
try:
from backend.services.email_service import get_email_service
email_service = get_email_service()
email_service.send_credit_review_needed_email(
email, "welcome", f"Evaluation error: {email}",
)
except Exception:
pass
return False, "pending_review"
else:
logger.info(f"Skipping credit evaluation for test email {email}")
# Grant welcome credits
welcome_credit = self.NEW_USER_FREE_CREDITS
transaction = CreditTransaction(
id=str(uuid.uuid4()),
amount=welcome_credit,
reason="welcome_credit",
)
transactions = user.credit_transactions[-MAX_CREDIT_TRANSACTIONS + 1:]
transactions.append(transaction)
new_balance = user.credits + welcome_credit
self.update_user(
email,
credits=new_balance,
credit_transactions=[t.model_dump(mode='json') for t in transactions],
welcome_credits_granted=True,
)
logger.info(f"Granted {welcome_credit} welcome credits to {email}")
return True, "granted"
except Exception:
logger.exception(f"Error granting welcome credits to {email}")
return False, "error"
# =========================================================================
# Anti-Abuse Rate Limiting
# =========================================================================
# Maximum new signups allowed per IP address in the rate limit window
# (Env-overridable only so the local E2E stack, where every browser signs up
# from 127.0.0.1, can raise it; production never sets it.)
MAX_SIGNUPS_PER_IP = _safe_positive_int_env("MAX_SIGNUPS_PER_IP", 2)
SIGNUP_RATE_LIMIT_HOURS = 24
# Higher cap for requests-board sign-ins: a shared venue WiFi can register many
# voters, but we still keep a deterministic ceiling against scripted abuse (each
# board account can later claim a welcome credit via /users/claim-welcome-credit).
# Applies to the shared-IP check ONLY — the per-fingerprint cap stays strict, since
# a venue is many devices on one IP, not many accounts on one device.
BOARD_MAX_SIGNUPS_PER_IP = _safe_positive_int_env("BOARD_MAX_SIGNUPS_PER_IP", 30)
def count_recent_signups_from_ip(self, ip_address: str, hours: int = 24) -> int:
"""
Count new user accounts created from this IP in the last N hours.
Queries gen_users where signup_ip matches and created_at is recent.
Used to rate-limit new account creation per IP address.
Args:
ip_address: Client IP to check
hours: Lookback window in hours (default: 24)
Returns:
Number of recent signups from this IP
"""
try:
cutoff = datetime.utcnow() - timedelta(hours=hours)
query = (
self.db.collection(USERS_COLLECTION)
.where(filter=FieldFilter("signup_ip", "==", ip_address))
.where(filter=FieldFilter("created_at", ">=", cutoff))
.order_by("created_at", direction=firestore.Query.DESCENDING)
)
count = 0
for _ in query.stream():
count += 1
return count
except Exception:
logger.exception(f"Error counting signups from IP {ip_address}")
# On error, don't block — return 0 to allow the request
return 0
def count_recent_signups_from_fingerprint(
self, device_fingerprint: str, hours: int = 24
) -> int:
"""
Count new user accounts created with this device fingerprint in the last N hours.
Args:
device_fingerprint: Browser fingerprint to check
hours: Lookback window in hours (default: 24)
Returns:
Number of recent signups from this fingerprint
"""
try:
cutoff = datetime.utcnow() - timedelta(hours=hours)
query = (
self.db.collection(USERS_COLLECTION)
.where(filter=FieldFilter("device_fingerprint", "==", device_fingerprint))
.where(filter=FieldFilter("created_at", ">=", cutoff))
.order_by("created_at", direction=firestore.Query.DESCENDING)
)
count = 0
for _ in query.stream():
count += 1
return count
except Exception:
logger.exception(f"Error counting signups from fingerprint")
return 0
def is_signup_rate_limited(
self,
ip_address: Optional[str] = None,
device_fingerprint: Optional[str] = None,
max_signups: Optional[int] = None,
) -> bool:
"""
Check if a signup should be rate limited based on IP and/or fingerprint.
Either signal hitting the limit triggers a block. `max_signups` overrides the
per-IP cap ONLY — the requests board passes a higher limit (BOARD_MAX_SIGNUPS_PER_IP)
so a whole venue on shared WiFi can sign in. The per-fingerprint cap always stays
strict (self.MAX_SIGNUPS_PER_IP): a venue is many devices behind one IP, so raising
the fingerprint cap would let one browser script many accounts.
"""
ip_limit = max_signups if max_signups is not None else self.MAX_SIGNUPS_PER_IP
if ip_address:
ip_count = self.count_recent_signups_from_ip(
ip_address, hours=self.SIGNUP_RATE_LIMIT_HOURS
)
if ip_count >= ip_limit:
return True
if device_fingerprint:
fp_count = self.count_recent_signups_from_fingerprint(
device_fingerprint, hours=self.SIGNUP_RATE_LIMIT_HOURS
)
if fp_count >= self.MAX_SIGNUPS_PER_IP:
return True
return False
# =========================================================================
# Anti-Abuse Investigation
# =========================================================================
def find_users_by_signup_ip(self, ip_address: str) -> List[User]:
"""Find all users who signed up from this IP address."""
try:
query = (
self.db.collection(USERS_COLLECTION)
.where(filter=FieldFilter("signup_ip", "==", ip_address))
.order_by("created_at", direction=firestore.Query.DESCENDING)
.limit(50)
)
return [User(**doc.to_dict()) for doc in query.stream()]
except Exception:
logger.exception(f"Error finding users by IP {ip_address}")
return []
def find_users_by_fingerprint(self, device_fingerprint: str) -> List[User]:
"""Find all users who signed up with this device fingerprint."""
try:
query = (
self.db.collection(USERS_COLLECTION)
.where(filter=FieldFilter("device_fingerprint", "==", device_fingerprint))
.order_by("created_at", direction=firestore.Query.DESCENDING)
.limit(50)
)
return [User(**doc.to_dict()) for doc in query.stream()]
except Exception:
logger.exception(f"Error finding users by fingerprint")
return []
def find_suspicious_accounts(self, min_jobs: int = 2, max_spend: int = 0) -> List[User]:
"""
Find accounts with many jobs but no spend (potential free-credit abusers).
Args:
min_jobs: Minimum total_jobs_created to flag (default: 2)
max_spend: Maximum total_spent in cents to include (default: 0 = free only)
"""
from backend.utils.test_data import is_internal_or_test_email
try:
query = (
self.db.collection(USERS_COLLECTION)
.where(filter=FieldFilter("total_jobs_created", ">=", min_jobs))
.order_by("total_jobs_created", direction=firestore.Query.DESCENDING)
.limit(100)
)
users = []
for doc in query.stream():
user = User(**doc.to_dict())
if user.total_spent <= max_spend and not is_internal_or_test_email(user.email):
users.append(user)
return users
except Exception:
logger.exception("Error finding suspicious accounts")
return []
def find_related_accounts(self, email: str) -> dict:
"""
Given a user email, find all accounts that share the same signup IP
or device fingerprint. Returns a dict with grouped results.
"""
user = self.get_user(email)
if not user:
return {"user": None, "by_ip": [], "by_fingerprint": []}
by_ip = []
if user.signup_ip:
by_ip = [
u for u in self.find_users_by_signup_ip(user.signup_ip)
if u.email != user.email
]
by_fingerprint = []
if user.device_fingerprint:
by_fingerprint = [
u for u in self.find_users_by_fingerprint(user.device_fingerprint)
if u.email != user.email
]
return {
"user": user,
"by_ip": by_ip,
"by_fingerprint": by_fingerprint,
}
def find_account_correlations(self) -> dict:
"""
Find clusters of accounts sharing the same fingerprint or signup IP.
Returns groups of 2+ accounts that share the same identifier,
sorted by group size (largest first). Excludes internal/test accounts.
"""
from collections import defaultdict
from backend.utils.test_data import is_internal_or_test_email
# Known bad IPs (load balancer, metadata, placeholder) that don't represent real client IPs
BAD_IPS = {"169.254.169.126", "unknown", ""}
try:
all_users = []
for doc in self.db.collection(USERS_COLLECTION).stream():
user = User(**doc.to_dict())
if not is_internal_or_test_email(user.email):
all_users.append(user)
# Group by fingerprint
fp_groups: dict[str, list[User]] = defaultdict(list)
for user in all_users:
if user.device_fingerprint:
fp_groups[user.device_fingerprint].append(user)
# Group by IP (exclude known bad IPs)
ip_groups: dict[str, list[User]] = defaultdict(list)
for user in all_users:
if user.signup_ip and user.signup_ip not in BAD_IPS:
ip_groups[user.signup_ip].append(user)
# Collect user agents from latest sessions for users in clusters
cluster_emails = set()
for fp, users in fp_groups.items():
if len(users) >= 2:
cluster_emails.update(u.email for u in users)
for ip, users in ip_groups.items():
if len(users) >= 2:
cluster_emails.update(u.email for u in users)
user_agents: dict[str, str] = {}
for email in cluster_emails:
try:
sessions = (
self.db.collection(SESSIONS_COLLECTION)
.where(filter=FieldFilter("user_email", "==", email))
.order_by("created_at", direction=firestore.Query.DESCENDING)
.limit(1)
.stream()
)
for session_doc in sessions:
session_data = session_doc.to_dict()
ua = session_data.get("user_agent")
if ua:
user_agents[email] = ua
except Exception:
pass # Skip if session lookup fails
# Build response - only clusters with 2+ users
fingerprint_clusters = []
for fp, users in fp_groups.items():
if len(users) >= 2:
fingerprint_clusters.append({
"fingerprint": fp,
"users": sorted(users, key=lambda u: u.created_at or "", reverse=True),
})
fingerprint_clusters.sort(key=lambda c: len(c["users"]), reverse=True)
ip_clusters = []
for ip, users in ip_groups.items():
if len(users) >= 2:
ip_clusters.append({
"ip": ip,
"users": sorted(users, key=lambda u: u.created_at or "", reverse=True),
})
ip_clusters.sort(key=lambda c: len(c["users"]), reverse=True)
return {
"fingerprint_clusters": fingerprint_clusters,
"ip_clusters": ip_clusters,
"user_agents": user_agents,
}
except Exception:
logger.exception("Error finding account correlations")
return {"fingerprint_clusters": [], "ip_clusters": [], "user_agents": {}}
# =========================================================================
# Session Management
# =========================================================================
def create_session(
self,
user_email: str,
ip_address: Optional[str] = None,
user_agent: Optional[str] = None,
tenant_id: Optional[str] = None,
device_fingerprint: Optional[str] = None,
) -> Session:
"""
Create a new session for an authenticated user.
Args:
user_email: User's email address
ip_address: Client IP for auditing
user_agent: Client user agent for auditing
tenant_id: Tenant ID for white-label portals (None = default Nomad Karaoke)
device_fingerprint: Browser fingerprint for cross-account correlation
"""
token = secrets.token_urlsafe(32)
token_prefix = token[:12]
session = Session(
token=token,
user_email=user_email.lower(),
expires_at=datetime.utcnow() + timedelta(days=SESSION_ABSOLUTE_EXPIRY_DAYS),
ip_address=ip_address,
user_agent=user_agent,
tenant_id=tenant_id,
device_fingerprint=device_fingerprint,
)
# Serialize and write to Firestore
session_data = session.model_dump(mode='json')
doc_ref = self.db.collection(SESSIONS_COLLECTION).document(token)
doc_ref.set(session_data)
# Verify the write succeeded by reading back
verify_doc = doc_ref.get()
if not verify_doc.exists:
logger.error(f"Session write verification FAILED for {user_email}: {token_prefix}...")
raise RuntimeError(f"Failed to persist session for {user_email}")
logger.info(f"Created and verified session for {user_email}: {token_prefix}... (expires: {session.expires_at})")
return session
def validate_session(self, token: str) -> Tuple[bool, Optional[User], str]:
"""
Validate a session token.
Returns:
(valid, user, message)
"""
# Log token info for debugging (only prefix for security)
token_prefix = token[:12] if token and len(token) >= 12 else token
logger.debug(f"Validating session token: {token_prefix}... (len={len(token) if token else 0})")
try:
doc_ref = self.db.collection(SESSIONS_COLLECTION).document(token)
doc = doc_ref.get()
if not doc.exists:
logger.warning(f"Session not found in Firestore: {token_prefix}...")
return False, None, "Invalid session"
raw_data = doc.to_dict()
logger.debug(f"Session data found for {token_prefix}...: user_email={raw_data.get('user_email')}, is_active={raw_data.get('is_active')}")
session = Session(**raw_data)
# Check if active
if not session.is_active:
logger.warning(f"Session revoked for {token_prefix}... (user: {session.user_email})")
return False, None, "Session has been revoked"
# Use timezone-aware datetime for all comparisons
# Firestore returns timezone-aware datetimes, so we must use aware datetimes
now = datetime.now(timezone.utc)
# Normalize session datetimes to be timezone-aware for comparison
# (handles legacy naive datetimes that may exist in Firestore)
expires_at = session.expires_at
if expires_at.tzinfo is None:
expires_at = expires_at.replace(tzinfo=timezone.utc)
last_activity = session.last_activity_at
if last_activity.tzinfo is None:
last_activity = last_activity.replace(tzinfo=timezone.utc)
# Check expiry
if now > expires_at:
logger.warning(f"Session expired for {token_prefix}... (user: {session.user_email}, expired_at: {expires_at}, now: {now})")
return False, None, "Session has expired"
# Check inactivity (7 days)
inactivity_limit = now - timedelta(days=SESSION_EXPIRY_DAYS)
if last_activity < inactivity_limit:
logger.warning(f"Session inactive for {token_prefix}... (user: {session.user_email}, last_activity: {last_activity}, limit: {inactivity_limit})")
return False, None, "Session expired due to inactivity"
# Update last activity (use timezone-aware datetime)
doc_ref.update({'last_activity_at': now})
# Get user
user = self.get_user(session.user_email)
if not user:
logger.warning(f"User not found for session {token_prefix}...: {session.user_email}")
return False, None, "User not found"
if not user.is_active:
logger.warning(f"User account disabled for session {token_prefix}...: {session.user_email}")
return False, None, "User account is disabled"
logger.debug(f"Session valid for {token_prefix}... (user: {user.email}, credits: {user.credits})")
return True, user, "Valid session"
except Exception:
logger.exception(f"Error validating session {token_prefix}...")
return False, None, "An error occurred during validation"
def revoke_session(self, token: str) -> bool:
"""Revoke a session (logout).
Idempotent: a session document that no longer exists is already
revoked, so a missing document is treated as success rather than an
error. Firestore's ``update()`` raises NotFound when the document is
absent (e.g. already logged out, or expired/cleaned up).
"""
try:
doc_ref = self.db.collection(SESSIONS_COLLECTION).document(token)
doc_ref.update({'is_active': False})
logger.info("Session revoked")
return True
except google_exceptions.NotFound:
logger.info("Session already absent; treating revoke as success")
return True
except Exception:
logger.exception("Error revoking session")
return False
def revoke_all_sessions(self, user_email: str) -> int:
"""Revoke all sessions for a user."""
try:
query = self.db.collection(SESSIONS_COLLECTION).where(
filter=FieldFilter('user_email', '==', user_email.lower())
).where(
filter=FieldFilter('is_active', '==', True)
)
count = 0
for doc in query.stream():
doc.reference.update({'is_active': False})
count += 1
logger.info(f"Revoked {count} sessions for {user_email}")
return count
except Exception:
logger.exception("Error revoking sessions")
return 0
def list_sessions_for_user(
self,
user_email: str,
include_revoked: bool = False,
limit: int = 50
) -> List[Session]:
"""
List all sessions for a user.
Args:
user_email: User's email address
include_revoked: If True, include revoked/inactive sessions
limit: Maximum number of sessions to return
Returns:
List of Session objects, ordered by created_at descending
"""
try:
query = self.db.collection(SESSIONS_COLLECTION).where(
filter=FieldFilter('user_email', '==', user_email.lower())
)
if not include_revoked:
query = query.where(filter=FieldFilter('is_active', '==', True))
query = query.order_by('created_at', direction=firestore.Query.DESCENDING)
query = query.limit(limit)
sessions = []
for doc in query.stream():
try:
sessions.append(Session(**doc.to_dict()))
except Exception as e:
logger.warning(f"Failed to parse session document: {e}")
logger.debug(f"Found {len(sessions)} sessions for {user_email}")
return sessions
except Exception:
logger.exception(f"Error listing sessions for {user_email}")
return []
# =========================================================================
# Credit Operations
# =========================================================================
def add_credits(self, email: str, *args, **kwargs) -> Tuple[bool, int, str]:
"""Add credits (see _add_credits_unlocked). Serialized per user within this
instance — the read-modify-write isn't transactional, and threadpool route
handlers could otherwise interleave two grants and lose one."""
with user_lock(email):
return self._add_credits_unlocked(email, *args, **kwargs)
def _add_credits_unlocked(
self,
email: str,
amount: int,
reason: str,
job_id: Optional[str] = None,
stripe_session_id: Optional[str] = None,
admin_email: Optional[str] = None
) -> Tuple[bool, int, str]:
"""
Add credits to a user account.
Returns:
(success, new_balance, message)
"""
try:
# For Stripe sessions, atomically check and mark as processed
# Uses create() which fails if document exists - ensures idempotency
if stripe_session_id:
doc_ref = self.db.collection(PROCESSED_STRIPE_SESSIONS_COLLECTION).document(stripe_session_id)
try:
doc_ref.create({
'stripe_session_id': stripe_session_id,
'email': email.lower(),
'amount': amount,
'processed_at': datetime.utcnow()
})
except google_exceptions.AlreadyExists:
# Document already exists - this session was already processed
logger.info(f"Stripe session {stripe_session_id} already processed (idempotent skip)")
return False, 0, "Session already processed"
email = email.lower()
user = self.get_or_create_user(email)
# Create transaction record
transaction = CreditTransaction(
id=str(uuid.uuid4()),
amount=amount,
reason=reason,
job_id=job_id,
stripe_session_id=stripe_session_id,
created_by=admin_email,
)
# Add to transaction history (keep last N)
transactions = user.credit_transactions[-MAX_CREDIT_TRANSACTIONS + 1:]
transactions.append(transaction)
# Update user
new_balance = user.credits + amount
self.update_user(
email,
credits=new_balance,
credit_transactions=[t.model_dump(mode='json') for t in transactions]
)
logger.info(f"Added {amount} credits to {email} ({reason}). New balance: {new_balance}")
return True, new_balance, f"Added {amount} credits"
except Exception as e:
logger.exception(f"Error adding credits to {email}")
return False, 0, f"Failed to add credits: {e}"
def deduct_credits(
self,
email: str,
job_id: str,
amount: int = 1,
reason: str = "job_creation",
count_as_job_creation: bool = True,
) -> Tuple[bool, int, str]:
"""
Atomically deduct N credits from a user account (all-or-nothing).
Uses Firestore transaction to prevent race conditions.
Args:
email: User email address.
job_id: Job ID associated with the deduction.
amount: Number of credits to deduct (default: 1, must be > 0).
reason: Reason for the deduction (default: "job_creation").
count_as_job_creation: When True (default), increments
``total_jobs_created`` by 1. Pass False when deducting
*additional* credits for an already-existing job (e.g. the
reconcile/top-up path) so the counter is not double-counted.
Returns:
(success, remaining_credits, message)
"""
if amount <= 0:
return False, 0, "Deduction amount must be positive"
try:
email = email.lower()
doc_ref = self.db.collection(USERS_COLLECTION).document(email)
@firestore.transactional
def deduct_in_transaction(transaction):
"""Atomically check and deduct credits."""
doc = doc_ref.get(transaction=transaction)
if not doc.exists:
return False, 0, "User not found"
user_data = doc.to_dict()
current_credits = user_data.get('credits', 0)
if current_credits < amount:
return False, current_credits, "Insufficient credits"
# Create transaction record
credit_txn = CreditTransaction(
id=str(uuid.uuid4()),
amount=-amount,
reason=reason,
job_id=job_id,
)
# Get existing transactions and add new one
existing_transactions = user_data.get('credit_transactions', [])
# Keep last N-1 transactions to make room for new one
transactions = existing_transactions[-(MAX_CREDIT_TRANSACTIONS - 1):]
transactions.append(credit_txn.model_dump(mode='json'))
# Calculate new values
new_balance = current_credits - amount
update_payload = {
'credits': new_balance,
'credit_transactions': transactions,
'updated_at': datetime.utcnow(),
}
if count_as_job_creation:
update_payload['total_jobs_created'] = user_data.get('total_jobs_created', 0) + 1
# Update atomically within transaction
transaction.update(doc_ref, update_payload)
return True, new_balance, f"Deducted {amount} credit(s). {new_balance} remaining"
# Execute the transaction
fs_transaction = self.db.transaction()
success, new_balance, message = deduct_in_transaction(fs_transaction)
if success:
logger.info(f"Deducted {amount} credit(s) from {email} for job {job_id}. Remaining: {new_balance}")
return success, new_balance, message
except Exception as e:
logger.exception(f"Error deducting credit(s) from {email}")
return False, 0, f"Failed to deduct credit: {e}"
def deduct_credit(
self,
email: str,
job_id: str,
reason: str = "job_creation"
) -> Tuple[bool, int, str]:
"""
Deduct one credit from a user account.
Thin wrapper around deduct_credits(amount=1). Preserved for backwards
compatibility with all existing callers.
Returns:
(success, remaining_credits, message)
"""
return self.deduct_credits(email, job_id, amount=1, reason=reason)
def refund_credit(
self,
email: str,
job_id: str,
reason: str = "job_failed"
) -> Tuple[bool, int, str]:
"""
Refund one credit to a user account (e.g., after job failure).
Returns:
(success, new_balance, message)
"""
return self.add_credits(email, 1, reason, job_id=job_id)
def check_credits(self, email: str) -> int:
"""Check user's credit balance."""
user = self.get_user(email)
return user.credits if user else 0
def has_credits(self, email: str) -> bool:
"""Check if user has at least one credit."""
return self.check_credits(email) > 0
def is_stripe_session_processed(self, stripe_session_id: str) -> bool:
"""
Check if a Stripe session ID has already been processed.
Used to ensure idempotency of webhook processing - prevents
duplicate credit additions if Stripe sends the same webhook twice.
Uses a dedicated collection for O(1) lookup instead of scanning all users.
Args:
stripe_session_id: The Stripe checkout session ID
Returns:
True if this session was already processed
"""
try:
doc_ref = self.db.collection(PROCESSED_STRIPE_SESSIONS_COLLECTION).document(stripe_session_id)
doc = doc_ref.get()
if doc.exists:
logger.info(f"Stripe session {stripe_session_id} already processed")
return True
return False
except Exception:
logger.exception(f"Error checking if stripe session {stripe_session_id} was processed")
# On error, return False to allow processing (better to risk duplicate than block)
return False
def _mark_stripe_session_processed(self, stripe_session_id: str, email: str, amount: int) -> None:
"""
Mark a Stripe session as processed.
Called after successfully adding credits from a Stripe webhook.
Args:
stripe_session_id: The Stripe checkout session ID
email: User email who received the credits
amount: Number of credits added
"""
try:
doc_ref = self.db.collection(PROCESSED_STRIPE_SESSIONS_COLLECTION).document(stripe_session_id)
doc_ref.set({
'stripe_session_id': stripe_session_id,
'email': email,
'amount': amount,
'processed_at': datetime.utcnow()
})
except Exception:
# Log but don't fail - the credits were already added
logger.exception(f"Error marking stripe session {stripe_session_id} as processed")
# =========================================================================
# Admin Operations
# =========================================================================
def set_user_role(self, email: str, role: UserRole, admin_email: str) -> bool:
"""Set a user's role (admin only)."""
try:
user = self.get_user(email)
if not user:
return False
self.update_user(email, role=role.value)
logger.info(f"Admin {admin_email} set role for {email} to {role.value}")
return True
except Exception:
logger.exception("Error setting user role")
return False
def disable_user(self, email: str, admin_email: str) -> bool:
"""Disable a user account (admin only)."""
try:
self.update_user(email, is_active=False)
self.revoke_all_sessions(email)
logger.info(f"Admin {admin_email} disabled user {email}")
return True
except Exception:
logger.exception("Error disabling user")
return False
def enable_user(self, email: str, admin_email: str) -> bool:
"""Enable a user account (admin only)."""
try:
self.update_user(email, is_active=True)
logger.info(f"Admin {admin_email} enabled user {email}")
return True
except Exception:
logger.exception("Error enabling user")
return False
def delete_user(self, email: str, admin_email: str) -> bool:
"""
Permanently delete a user and all their associated data.
Deletes: user document, sessions, magic links.
Does NOT delete jobs (they remain as historical records).
Args:
email: Email of the user to delete
admin_email: Email/ID of the admin performing the action
Returns:
True if user was deleted, False if user not found
Raises:
ValueError: If trying to delete an admin user
"""
try:
email = email.lower()
user = self.get_user(email)
if not user:
return False
if user.role == UserRole.ADMIN:
raise ValueError("Cannot delete admin users")
# Revoke all active sessions
self.revoke_all_sessions(email)
# Delete magic links for the user
magic_links = self.db.collection(MAGIC_LINKS_COLLECTION).where(
filter=FieldFilter('email', '==', email)
).stream()
for doc in magic_links:
doc.reference.delete()
# Delete the user document
self.db.collection(USERS_COLLECTION).document(email).delete()
logger.info(f"Admin {admin_email} permanently deleted user {email}")
return True
except ValueError:
raise
except Exception:
logger.exception(f"Error deleting user {email}")
return False
def increment_jobs_completed(self, email: str) -> bool:
"""Increment the completed jobs counter for a user using atomic increment."""
try:
doc_ref = self.get_user_doc_ref(email)
if not doc_ref:
return False
doc_ref.update({
'total_jobs_completed': Increment(1),
'updated_at': datetime.utcnow()
})
return True
except Exception:
logger.exception(f"Error incrementing jobs completed for {email}")
return False
# Global instance
_user_service = None
def get_user_service() -> UserService:
"""Get the global user service instance."""
global _user_service
if _user_service is None:
_user_service = UserService()
return _user_service