Files
karaoke-gen/backend/services/login_code_store.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

274 lines
11 KiB
Python

"""Reusable emailed sign-in code store (6-digit codes, HMAC-hashed at rest).
Shared by gen's own email-code sign-in (``/api/users/auth/send-code`` +
``verify-code``, collections ``login_codes`` / ``login_code_uses``) and the kjbox
partner API (``KjboxPartnerService``, collections ``kjbox_login_codes`` /
``kjbox_login_code_uses``). Each caller picks its own collections, so the two
flows never share codes or throttle state.
Per collection pair:
- ``<codes_collection>`` one doc per email (id = sha256(email)); holds only an
HMAC of the current code, its expiry + attempt counter,
the recent send timestamps (per-email throttle), caller
metadata (locale, IP, ...) and the precomputed
welcome-credit evaluation.
- ``<uses_collection>`` create()-only markers keyed by code_id — makes a code
strictly single-use even under concurrent verifies.
- ``<ip_collection>`` optional; one doc per sha256(client IP) with recent send
timestamps (per-IP throttle). Only touched when the
caller passes ``throttle_ip``.
Throttle decisions run inside ONE Firestore transaction together with the code
write, so concurrent sends can't slip past either limit.
"""
from __future__ import annotations
import hashlib
import hmac
import secrets
from dataclasses import dataclass
from datetime import datetime, timedelta, timezone
from typing import Any, Callable, Optional
from google.api_core import exceptions as google_exceptions
from google.cloud import firestore
from google.cloud.firestore_v1 import Increment
CODE_LENGTH = 6
CODE_EXPIRY_MINUTES = 10
MAX_VERIFY_ATTEMPTS = 5
TRANSACTION_MAX_ATTEMPTS = 10
THROTTLE_WINDOW = timedelta(hours=1)
def _now() -> datetime:
return datetime.now(timezone.utc)
def _aware(dt: Any) -> Optional[datetime]:
"""Normalize Firestore/ISO timestamps to tz-aware UTC datetimes."""
if dt is None:
return None
if isinstance(dt, str):
try:
dt = datetime.fromisoformat(dt)
except ValueError:
return None
if not isinstance(dt, datetime):
return None
return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
def _sha256(value: str) -> str:
return hashlib.sha256(value.encode("utf-8")).hexdigest()
def code_doc_id(email: str) -> str:
return _sha256(email.strip().lower())
def recent_times(values, now: Optional[datetime] = None, window: timedelta = THROTTLE_WINDOW) -> list:
"""Timestamps from ``values`` that fall inside the rolling ``window``."""
now = now or _now()
times = [_aware(t) for t in values or []]
return [t for t in times if t and now - t < window]
@dataclass
class IssuedCode:
code: str
doc_id: str
needs_credit_eval: bool
class TransactionContention(Exception):
"""A Firestore transaction gave up after repeated contention (nothing written)."""
class CodeThrottled(Exception):
"""Per-email (or per-IP) code throttle hit (raised out of the issue transaction)."""
class VerifyOutcome:
OK = "ok"
EXPIRED = "expired"
INVALID = "invalid_code"
TOO_MANY_ATTEMPTS = "too_many_attempts"
def run_firestore_transaction(db, fn: Callable):
"""Run ``fn(transaction)`` under @firestore.transactional (retried on contention).
google-cloud-firestore gives up with ValueError("Failed to commit transaction
in N attempts.") under heavy contention. Nothing was written, so it's mapped
to :class:`TransactionContention` for callers to treat as "busy, retry".
"""
try:
return firestore.transactional(fn)(db.transaction(max_attempts=TRANSACTION_MAX_ATTEMPTS))
except ValueError as exc:
if "Failed to commit transaction" in str(exc):
raise TransactionContention() from exc
raise
class LoginCodeStore:
"""Issue + verify emailed 6-digit sign-in codes in a given pair of collections."""
def __init__(
self,
db,
pepper: str,
codes_collection: str,
uses_collection: str,
transaction_runner: Optional[Callable] = None,
ip_collection: Optional[str] = None,
):
self.db = db
# A server-side secret pepper: a Firestore read alone (backups, exports)
# can't brute-force the 10^6 code space offline.
self._pepper = pepper.encode("utf-8")
self.codes_collection = codes_collection
self.uses_collection = uses_collection
self.ip_collection = ip_collection
# Injectable for unit tests (in-memory Firestore fake) and so callers
# (KjboxPartnerService) can route through their own runner.
self._transaction_runner = transaction_runner
def _run_transaction(self, fn):
if self._transaction_runner is not None:
return self._transaction_runner(fn)
return run_firestore_transaction(self.db, fn)
def hash_code(self, code_id: str, code: str) -> str:
return hmac.new(self._pepper, f"{code_id}:{code}".encode("utf-8"), hashlib.sha256).hexdigest()
def code_ref(self, email: str):
return self.db.collection(self.codes_collection).document(code_doc_id(email))
def _ip_ref(self, ip_address: str):
return self.db.collection(self.ip_collection).document(_sha256(ip_address))
def get_code_record(self, email: str) -> Optional[dict]:
snap = self.code_ref(email).get()
return snap.to_dict() if snap.exists else None
def recent_send_times(self, record: Optional[dict], now: Optional[datetime] = None) -> list:
return recent_times((record or {}).get("send_times"), now)
def issue_code(
self,
email: str,
*,
max_per_hour: int,
needs_credit_eval: bool,
fields: Optional[dict] = None,
throttle_ip: Optional[str] = None,
max_per_ip_per_hour: Optional[int] = None,
) -> IssuedCode:
"""Mint a fresh code for ``email``, replacing (invalidating) any prior one.
The throttle checks, the send_times appends and the code write happen in
ONE transaction, so parallel requests can't exceed ``max_per_hour`` sends
per email (nor ``max_per_ip_per_hour`` per ``throttle_ip`` when given) —
raises :class:`CodeThrottled`. A throttled request records nothing.
Only an HMAC of the code is stored. ``merge=True`` keeps any precomputed
welcome-credit evaluation across re-sends. ``fields`` (locale, IP, venue,
tenant, ...) are stored on the record and returned by verify_code.
"""
email = email.strip().lower()
ref = self.code_ref(email)
ip_ref = None
if throttle_ip and max_per_ip_per_hour is not None:
if not self.ip_collection:
raise ValueError("throttle_ip requires ip_collection")
ip_ref = self._ip_ref(throttle_ip)
def _txn(transaction):
now = _now()
# All reads before any write (Firestore transaction rule).
snap = ref.get(transaction=transaction)
ip_snap = ip_ref.get(transaction=transaction) if ip_ref is not None else None
record = snap.to_dict() if snap.exists else None
recent = self.recent_send_times(record, now)
if len(recent) >= max_per_hour:
raise CodeThrottled()
ip_recent = None
if ip_snap is not None:
ip_recent = recent_times((ip_snap.to_dict() or {}).get("send_times") if ip_snap.exists else None, now)
if len(ip_recent) >= max_per_ip_per_hour:
raise CodeThrottled()
code = f"{secrets.randbelow(10 ** CODE_LENGTH):0{CODE_LENGTH}d}"
code_id = secrets.token_urlsafe(16)
transaction.set(
ref,
{
**(fields or {}),
"email": email,
"code_id": code_id,
"code_hash": self.hash_code(code_id, code),
"created_at": now,
"expires_at": now + timedelta(minutes=CODE_EXPIRY_MINUTES),
"attempts": 0,
"send_times": recent + [now],
},
merge=True,
)
if ip_ref is not None:
# Only the IP hash is the doc id; the raw IP isn't stored here.
transaction.set(ip_ref, {"send_times": ip_recent + [now], "updated_at": now})
has_eval = bool((record or {}).get("credit_eval_decision"))
return IssuedCode(
code=code,
doc_id=code_doc_id(email),
needs_credit_eval=needs_credit_eval and not has_eval,
)
return self._run_transaction(_txn)
def verify_code(self, email: str, code: str) -> tuple[str, Optional[dict]]:
"""Check ``code`` for ``email``. Returns (outcome, code_record).
Attempts are counted with an atomic server-side increment BEFORE the
comparison, so parallel guesses can't exceed MAX_VERIFY_ATTEMPTS. A
success is claimed via a create()-only marker so a code works once.
"""
email = email.strip().lower()
ref = self.code_ref(email)
snap = ref.get()
record = snap.to_dict() if snap.exists else None
if not record or not record.get("code_hash") or not record.get("code_id"):
return VerifyOutcome.EXPIRED, None
expires_at = _aware(record.get("expires_at"))
if not expires_at or _now() > expires_at:
ref.update({"code_hash": None})
return VerifyOutcome.EXPIRED, None
ref.update({"attempts": Increment(1)})
after = ref.get().to_dict() or {}
if after.get("code_id") != record["code_id"] or not after.get("code_hash"):
# Superseded or burned between our read and the increment.
return VerifyOutcome.EXPIRED, None
if int(after.get("attempts") or 0) > MAX_VERIFY_ATTEMPTS:
ref.update({"code_hash": None})
return VerifyOutcome.TOO_MANY_ATTEMPTS, None
candidate = (code or "").strip()
expected = record["code_hash"]
provided = self.hash_code(record["code_id"], candidate)
if not (candidate.isdigit() and len(candidate) == CODE_LENGTH
and hmac.compare_digest(provided, expected)):
return VerifyOutcome.INVALID, None
try:
self.db.collection(self.uses_collection).document(record["code_id"]).create(
{"email": email, "used_at": _now()}
)
except google_exceptions.AlreadyExists:
return VerifyOutcome.EXPIRED, None
ref.update({"code_hash": None, "used_at": _now()})
return VerifyOutcome.OK, after