## Summary Three-layer defense against free credit abuse (disposable email bypass): - **Credits on verification**: Welcome credits granted on first magic link verification, not account creation. Unverified accounts get 0 credits. - **Per-IP rate limiting**: Max 2 new accounts per IP per 24 hours. Silent reject (anti-enumeration). - **Device fingerprinting**: FingerprintJS (open source) sends browser fingerprint with magic link request. Combined with IP — either signal hitting 2/day triggers block. Graceful degradation if fingerprinting fails. ## Changes ### Backend - `get_or_create_user()` creates users with 0 credits, stores `signup_ip` and `device_fingerprint` - New `grant_welcome_credits_if_eligible()` with `welcome_credits_granted` flag for idempotency - Verify endpoint grants credits and returns `credits_granted` in response - `count_recent_signups_from_ip()` and `count_recent_signups_from_fingerprint()` query Firestore - `is_signup_rate_limited()` combines IP + fingerprint signals - `send_magic_link` endpoint checks rate limit before creating magic link (new users only) - New fields: `User.signup_ip`, `User.device_fingerprint`, `User.welcome_credits_granted`, `MagicLinkToken.device_fingerprint`, `SendMagicLinkRequest.device_fingerprint`, `VerifyMagicLinkResponse.credits_granted` ### Frontend - New `fingerprint.ts` lib (lazy-loaded FingerprintJS) - `sendMagicLink` sends `device_fingerprint` with request - Verify page shows "You received N free credits to get started!" on first login - `VerifyMagicLinkResponse` type updated with `credits_granted` ### Tests - 33 unit + integration tests in `test_anti_abuse.py` - Covers: credit granting, idempotency, rate limiting (IP + fingerprint), error paths, caller-callee contracts, model fields, endpoint integration ## Testing - [x] All backend tests pass (33 new + existing) - [x] All frontend tests pass (707 tests) - [x] `make test` passes ## Review - [x] CodeRabbit CLI review completed locally - [x] Review feedback addressed (added `welcome_credits_granted` flag for idempotency) @coderabbitai ignore --- 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
17 KiB
Plan: Anti-Abuse Improvements for Free Credits System
Created: 2026-03-21 Branch: feat/sess-20260321-0043-anti-abuse-credits Status: Implemented
Overview
Three improvements to prevent abuse of the 2-free-credits-per-account system:
- Per-IP signup rate limiting — max 2 new accounts per IP per 24 hours
- Device fingerprinting — detect same-browser multi-account abuse
- Credits on verification, not creation — move welcome credits from account creation to first magic link verification
These are ordered by implementation complexity (simplest first) and can be shipped independently.
Background
Investigation of 60 recent signups (2026-03-20) found disposable email abuse and potential multi-account patterns. The disposable email detection (DeBounce + verifymail.io, shipped in v0.144.0) blocks throwaway email services, but doesn't prevent someone from creating multiple accounts with real emails from the same device/IP.
Part 1: Per-IP Signup Rate Limiting
Problem
No limit on how many accounts can be created from a single IP address. An abuser can create unlimited accounts from the same machine.
Approach
Track IP addresses on magic link requests (signup trigger). Before creating a magic link, check how many distinct new accounts were created from that IP in the last 24 hours. If >= 2, silently reject (return 200 to prevent enumeration, same pattern as blocked email/IP).
Why track at magic link request, not user creation?
- Magic link request is the user-facing action (they enter email, click "send")
- User creation happens inside
get_or_create_user()which is called during verification - Rate limiting at the entry point prevents even sending the email
Data model
Use the existing magic_links collection — it already stores ip_address and email. Query: count distinct emails with magic links created from this IP in the last 24 hours where the email doesn't already exist as a user.
No new collection needed. Just a query at magic link request time.
Implementation
File: backend/api/routes/users.py — send_magic_link() endpoint
After the disposable domain check and blocked email/IP checks (lines 157-175), add:
# Per-IP signup rate limit (only for new users)
existing_user = user_service.get_user(email)
if existing_user is None:
# This is a new signup — check IP rate limit
recent_signups = user_service.count_recent_signups_from_ip(
ip_address, hours=24
)
if recent_signups >= 2:
logger.warning(
f"IP signup rate limit hit: {ip_address} "
f"({recent_signups} signups in 24h)"
)
# Silent reject (anti-enumeration)
return SendMagicLinkResponse(
status="success",
message="If this email is registered, you will receive a login link."
)
File: backend/services/user_service.py
Add method:
def count_recent_signups_from_ip(self, ip_address: str, hours: int = 24) -> int:
"""Count distinct new-user magic link requests from this IP in the last N hours."""
cutoff = datetime.utcnow() - timedelta(hours=hours)
# Query magic_links where ip_address matches and created_at > cutoff
links = (
self.db.collection("magic_links")
.where("ip_address", "==", ip_address)
.where("created_at", ">=", cutoff.isoformat())
.stream()
)
# Count distinct emails that are NOT existing users
emails = set()
for link in links:
data = link.to_dict()
email = data.get("email", "")
# Only count if this email resulted in a new user creation
user_doc = self.db.collection("gen_users").document(email).get()
if user_doc.exists:
user_data = user_doc.to_dict()
created_at = user_data.get("created_at", "")
if created_at >= cutoff.isoformat():
emails.add(email)
return len(emails)
Optimization note: This approach queries Firestore for each magic link email. For production, a simpler approach would be to add a Firestore composite index on magic_links(ip_address, created_at) and count distinct emails in the result set. At our volume (~60 signups/day), the extra reads are negligible.
Alternative simpler approach: Instead of querying magic_links, track signups directly by adding signup_ip to the gen_users document at creation time. Then query gen_users where signup_ip == ip AND created_at >= cutoff. This is cleaner and avoids cross-collection queries.
Recommended: Use the simpler approach. Add signup_ip field to User model, set it in get_or_create_user(), and query it for rate limiting.
Edge cases
- Shared IPs (offices, universities, VPNs): 2 per day is generous enough for legitimate use. If a real user is blocked, they can try again tomorrow or contact support.
- IPv6 addresses: Rate limit on the full address. Don't try to normalize /64 subnets — too complex and most residential IPv6 users get a stable address.
- Existing users logging in: Rate limit only applies to new signups, not returning users.
169.254.169.126(load balancer IP): This is the LB IP seen on sessions/magic_links — need to ensure we're using the real client IP from X-Forwarded-For. Check howip_addressis set in the magic link endpoint. (From investigation: it useshttp_request.client.hostwhich should be the real IP behind Cloud Run's proxy, but verify.)
Tests
- Unit test:
count_recent_signups_from_ipreturns correct count - Unit test: rate limit triggered → silent 200 response
- Unit test: existing user login not rate limited
- Unit test: 1 signup from IP → allowed, 2nd → allowed, 3rd → blocked
- Integration test: magic link endpoint returns 200 (silent reject) when IP limit hit
Part 2: Device Fingerprinting
Problem
A determined abuser can use multiple IPs (VPN, mobile data, etc.) to bypass IP rate limiting. Device fingerprinting catches same-browser multi-account abuse regardless of IP.
Approach
Use FingerprintJS (open source, free) to generate a browser fingerprint on the frontend. Send it with the magic link request. Store it on the user document. Check it during signup rate limiting alongside IP.
Why FingerprintJS open source (not Pro)?
- Free, no API key needed
- Runs entirely client-side
- ~60-70% accuracy for identifying unique browsers (good enough as a signal, not sole blocker)
- Pro version ($0/mo for 20k identifications) is more accurate but adds external dependency
Data flow
Frontend: Generate fingerprint → send with magic link request
Backend: Store fingerprint on magic link → check at signup
Store fingerprint on user document → cross-reference
Frontend implementation
File: frontend/lib/fingerprint.ts (new)
import FingerprintJS from "@nicedayfor/fingerprintjs";
let cachedFingerprint: string | null = null;
export async function getDeviceFingerprint(): Promise<string> {
if (cachedFingerprint) return cachedFingerprint;
const fp = await FingerprintJS.load();
const result = await fp.get();
cachedFingerprint = result.visitorId;
return cachedFingerprint;
}
File: frontend/lib/auth.ts — modify requestMagicLink()
Add fingerprint to the magic link request body:
const fingerprint = await getDeviceFingerprint();
const response = await fetch("/api/users/auth/magic-link", {
method: "POST",
body: JSON.stringify({ email, device_fingerprint: fingerprint }),
});
Backend implementation
File: backend/api/routes/users.py
Add device_fingerprint: Optional[str] = None to SendMagicLinkRequest model.
Pass it through to create_magic_link() and store on the magic link document.
File: backend/models/user.py
Add device_fingerprint: Optional[str] = None to both MagicLinkToken and User models.
File: backend/services/user_service.py
- In
create_magic_link(): storedevice_fingerprinton the magic link doc - In
get_or_create_user(): storedevice_fingerprinton the user doc (from the magic link that triggered creation) - Add
count_recent_signups_from_fingerprint(): similar to IP rate limit but by fingerprint
Rate limiting with fingerprint
Combine IP and fingerprint signals:
# In send_magic_link endpoint, for new users:
ip_signups = user_service.count_recent_signups_from_ip(ip_address, hours=24)
fp_signups = user_service.count_recent_signups_from_fingerprint(
device_fingerprint, hours=24
) if device_fingerprint else 0
if ip_signups >= 2 or fp_signups >= 2:
# Silent reject
...
Edge cases
- No fingerprint sent (old clients, API users, bots): Fall back to IP-only rate limiting. Don't require fingerprint — it's an additional signal, not a hard requirement.
- Fingerprint collision: FingerprintJS open source has ~60-70% uniqueness. Two different people could get the same fingerprint. The 2-per-day limit is generous enough to handle occasional collisions.
- Incognito/private browsing: FingerprintJS still works reasonably well in incognito (canvas, WebGL, fonts are still consistent). Accuracy drops slightly.
- Browser extensions that block fingerprinting: Fall back to IP-only.
Tests
- Frontend: Unit test for fingerprint generation and caching
- Backend: Unit test for fingerprint storage on magic link and user
- Backend: Unit test for fingerprint-based rate limiting
- Backend: Integration test for combined IP + fingerprint rate limiting
- Backend: Test that missing fingerprint gracefully degrades to IP-only
Dependencies
# Frontend
npm install @nicedayfor/fingerprintjs
No backend dependencies needed (fingerprint is just a string).
Part 3: Credits on Verification, Not Creation
Problem
Currently, 2 welcome credits are granted in get_or_create_user() — at account creation time, before the user has verified their email. This means:
- Unverified accounts get credits (wasted if user never verifies)
- The user creation can be triggered by requesting a magic link (no verification needed)
- An attacker could create accounts and use credits without ever clicking a magic link
Approach
Move welcome credit granting from get_or_create_user() to the magic link verification endpoint (verify). Credits are only granted after the user successfully clicks the magic link (proving email ownership).
Implementation
File: backend/services/user_service.py — get_or_create_user()
Remove welcome credit granting:
# BEFORE (lines 125-142):
user = User(email=email, credits=NEW_USER_FREE_CREDITS, ...)
credit_transaction = CreditTransaction(
amount=NEW_USER_FREE_CREDITS, reason="welcome_credit", ...
)
# AFTER:
user = User(email=email, credits=0, ...)
# No credit transaction at creation
File: backend/services/user_service.py — new method
def grant_welcome_credits_if_eligible(self, email: str) -> bool:
"""Grant welcome credits on first verification, if not already granted."""
user = self.get_user(email)
if not user:
return False
# Check if welcome credits were already granted
for txn in user.credit_transactions:
if txn.reason == "welcome_credit":
return False # Already received
# Grant credits
self.add_credits(
email=email,
amount=NEW_USER_FREE_CREDITS,
reason="welcome_credit",
)
return True
File: backend/api/routes/users.py — verify endpoint
After successful verification (line ~283), add:
# Grant welcome credits on first verification
credits_granted = user_service.grant_welcome_credits_if_eligible(user.email)
if credits_granted:
logger.info(f"Granted {NEW_USER_FREE_CREDITS} welcome credits to {_mask_email(user.email)}")
Migration consideration
Existing users who signed up before this change already have their welcome credits. The grant_welcome_credits_if_eligible() method checks for existing welcome_credit transactions, so it won't double-grant.
Edge case: Users who signed up but haven't verified yet. These users have credits but haven't verified. After the change, they'll still have their credits (we don't revoke). When they eventually verify, the method sees the existing welcome_credit transaction and skips. No action needed.
Frontend impact
The verify response already includes the user's credit balance. The frontend should show a "You received 2 free credits!" message on first verification. Check if this already exists in the welcome flow.
File: frontend/app/auth/verify/page.tsx
The verify page already handles first-login detection (line ~57 checks for is_first_login in the response). We may need to add credits_granted to the verify response so the frontend can show a celebratory message.
Tests
- Unit test:
get_or_create_user()creates user with 0 credits - Unit test:
grant_welcome_credits_if_eligible()grants credits on first call - Unit test:
grant_welcome_credits_if_eligible()skips if already granted - Integration test: full flow — create user (0 credits) → verify magic link (2 credits)
- Integration test: verify twice → credits only granted once
Implementation Steps (All 3 Parts)
Phase 1: Credits on verification (Part 3) — lowest risk, highest impact
- Move credit granting from
get_or_create_user()to newgrant_welcome_credits_if_eligible() - Call
grant_welcome_credits_if_eligible()in verify endpoint - Add
credits_grantedto verify response - Update frontend verify page to show credit grant message
- Unit + integration tests
- Version bump, ship
Phase 2: Per-IP signup rate limiting (Part 1) — simple, effective
- Add
signup_ipfield to User model - Set
signup_ipinget_or_create_user()(passed from magic link endpoint) - Add
count_recent_signups_from_ip()method - Add rate limit check in
send_magic_link()endpoint (before sending email) - Unit + integration tests
- Version bump, ship
Phase 3: Device fingerprinting (Part 2) — most complex
- Install FingerprintJS in frontend
- Create
frontend/lib/fingerprint.ts - Send fingerprint with magic link request
- Add
device_fingerprintto MagicLinkToken and User models - Store fingerprint in
create_magic_link()andget_or_create_user() - Add
count_recent_signups_from_fingerprint()method - Combine IP + fingerprint rate limiting in
send_magic_link() - Unit + integration tests (frontend + backend)
- Version bump, ship
Files to Create/Modify
| File | Action | Part | Description |
|---|---|---|---|
backend/services/user_service.py |
Modify | 1,2,3 | Rate limit methods, credit granting changes, fingerprint storage |
backend/api/routes/users.py |
Modify | 1,2,3 | Rate limit check, credit grant on verify, fingerprint passthrough |
backend/models/user.py |
Modify | 1,2 | Add signup_ip, device_fingerprint fields |
backend/tests/test_user_service.py |
Modify | 1,2,3 | Tests for all new methods |
backend/tests/test_email_validation_integration.py |
Modify | 1 | Rate limit integration test |
frontend/lib/fingerprint.ts |
Create | 2 | FingerprintJS wrapper |
frontend/lib/auth.ts |
Modify | 2 | Send fingerprint with magic link request |
frontend/app/auth/verify/page.tsx |
Modify | 3 | Show credit grant message |
pyproject.toml |
Modify | 1,2,3 | Version bumps |
frontend/package.json |
Modify | 2 | Add FingerprintJS dependency |
Testing Strategy
- Unit tests: Mock Firestore for rate limit counting, credit granting, fingerprint storage
- Integration tests: TestClient for magic link → silent reject flow, verify → credit grant flow
- E2E test: After deploy, attempt signup with disposable domain (blocked), then attempt 3 signups from same IP (3rd blocked)
Open Questions
- Should we show a user-facing message when IP rate limited, or always silently reject? Recommendation: silent reject (anti-enumeration), same as blocked email/IP.
- Should fingerprint rate limiting be a hard block or just a signal for review? Recommendation: hard block (same as IP), since the 2-per-day limit is generous.
- Should we backfill
signup_ipfor existing users from their first magic link/session? Recommendation: no, not worth the complexity. Only applies to new signups going forward. - Should the feedback-for-credits flow also require verification? Recommendation: it already requires completed jobs, which implies verification. No change needed.
Rollback Plan
Each part can be rolled back independently:
- Credits on verification: Revert code → new users get credits at creation again. Existing verified users unaffected.
- IP rate limiting: Revert code → no rate limiting.
signup_ipfield remains on docs but unused. - Fingerprinting: Revert code → fingerprint not sent/stored. FingerprintJS dependency can be removed.
No data migrations needed for any rollback.