first commit

Made-with: Cursor

context/overview.md

@@ -0,0 +1,386 @@
+# Sats Faucet App
+
+## 1. Purpose
+
+Build a sats faucet web app that lets Nostr users claim a small, randomized sats payout (entropy payout) on a cooldown schedule, with strong anti-abuse protections.
+
+Key goals:
+
+* Fun community experiment that can evolve into a long-term public faucet.
+* Simple UX: connect Nostr, enter Lightning address, claim.
+* Abuse-resistant: NIP-98 signed requests, account age checks, activity scoring, per-pubkey cooldown, per-IP cooldown, and budget guards.
+* Transparent: public stats and recent payouts (anonymized).
+* Sustainable: daily budget cap, emergency stop switch, and minimum wallet balance guard.
+
+Non-goals:
+
+* Perfect Sybil resistance. The system raises the cost of abuse rather than claiming to fully prevent it.
+
+## 2. Core Requirements
+
+### 2.1 Claim rules
+
+A user may claim only if all conditions are true:
+
+* Authenticated via Nostr using NIP-98 signature on the claim request.
+* Account age is at least MIN_ACCOUNT_AGE_DAYS (default 14 days), based on earliest observed event timestamp on configured relays.
+* Activity score meets or exceeds MIN_ACTIVITY_SCORE.
+* Pubkey has not successfully claimed within the last COOLDOWN_DAYS (default 7 days).
+* IP has not successfully claimed within the last IP_COOLDOWN_DAYS (default 7 days) and under MAX_CLAIMS_PER_IP_PER_PERIOD.
+* Faucet is enabled and not in emergency stop.
+* LNbits wallet balance is at or above MIN_WALLET_BALANCE_SATS.
+* Daily budget not exceeded.
+
+### 2.2 Payout
+
+* Payout uses weighted randomness (entropy) configured by environment variables.
+* Reward amount is fixed per bucket (example buckets: 10, 25, 50, 100 sats), selected by weight.
+* The payout selected for a claim is locked to a short-lived quote to prevent re-rolling by refreshing.
+* Payout is sent via LNbits to a Lightning address provided by the user.
+
+### 2.3 Deposits
+
+* The app must display a deposit Lightning address and QR for community funding.
+* Preferred: LNURLp/Lightning Address for deposits (static address and QR).
+* Optional: allow users to create an invoice for a chosen deposit amount.
+
+### 2.4 Transparency
+
+Publicly visible:
+
+* Current faucet pool balance (from LNbits).
+* Total sats paid.
+* Total claim count.
+* Claims in last 24h.
+* Daily budget and daily spend.
+* Recent claims list (anonymized, limited number).
+
+## 3. System Overview
+
+### 3.1 Components
+
+1. Frontend Web App
+
+   * Connect Nostr (NIP-07 or external signer).
+   * Collect Lightning address.
+   * Calls backend to get a quote and confirm claim.
+   * Shows eligibility failures with friendly reasons and next eligible time.
+   * Shows deposit info and public transparency stats.
+
+2. Faucet Backend API
+
+   * Validates NIP-98 signed requests.
+   * Resolves client IP safely (with proxy support).
+   * Enforces cooldown locks and rate limiting.
+   * Fetches Nostr metadata + activity from relays and caches it.
+   * Computes account age and activity score.
+   * Computes payout quote, enforces daily budget, executes LNbits payout.
+   * Records claims, payout results, and stats.
+
+3. LNbits
+
+   * Holds the faucet wallet.
+   * Executes outgoing payments.
+   * Provides deposit address (Lightning Address/LNURLp).
+
+### 3.2 Trust boundaries
+
+* LNbits keys live only on the backend.
+* Frontend never sees LNbits keys.
+* Backend stores only HMAC-hashed IPs, not raw IPs.
+* Lightning address should not be stored in plaintext unless explicitly desired; store a hash for privacy.
+
+## 4. User Experience
+
+### 4.1 Home page
+
+* Primary call-to-action: Claim sats.
+* Deposit section:
+
+  * Show DEPOSIT_LIGHTNING_ADDRESS.
+  * Show QR code for DEPOSIT_LNURLP (or encoded LNURL).
+  * Optional button: Create deposit invoice.
+* Live stats:
+
+  * Balance, total paid, total claims, last 24h.
+  * Recent payouts list.
+* Rules summary:
+
+  * Cooldown days, min age, min score, per-IP limit.
+
+### 4.2 Claim flow
+
+1. User clicks Connect Nostr.
+2. User enters Lightning address.
+3. User clicks Check / Quote.
+4. App shows:
+
+   * If ineligible: exact reason and next eligible time.
+   * If eligible: payout amount and Confirm button.
+5. User confirms.
+6. App shows success state:
+
+   * payout amount
+   * status
+   * next eligible date
+
+UI must clearly separate:
+
+* Eligibility check
+* Payment attempt
+
+## 5. Backend Behavior
+
+### 5.1 NIP-98 authentication
+
+The backend must verify each protected request:
+
+* Signature is valid for the provided pubkey.
+* Signed payload includes correct method and URL.
+* Timestamp is within NIP98_MAX_SKEW_SECONDS.
+* Nonce is present and not reused (store for NONCE_TTL_SECONDS).
+
+### 5.2 IP handling
+
+* Backend must support TRUST_PROXY mode.
+* When TRUST_PROXY=true, derive IP from X-Forwarded-For correctly.
+* Hash IP using HMAC_IP_SECRET and store only the hash.
+
+### 5.3 Eligibility engine
+
+For a given pubkey and ip_hash:
+
+* Check emergency stop and faucet enabled flags.
+* Check wallet balance guard.
+* Check per-pubkey cooldown: latest successful claim timestamp.
+* Check per-IP cooldown: latest successful claim timestamp and quota.
+* Fetch or load cached Nostr profile and activity metrics.
+* Verify account age and activity score.
+
+Return structured result:
+
+* eligible: boolean
+* denial_reason: enum
+* denial_message: user-friendly text
+* next_eligible_at: timestamp if applicable
+
+### 5.4 Quote then confirm
+
+Use a two-step claim to prevent payout rerolling.
+
+POST /claim/quote
+
+* Auth required (NIP-98)
+* Input: lightning_address
+* Performs full eligibility check.
+* Selects payout using weighted randomness.
+* Enforces daily budget guard:
+
+  * If today_spent + payout > DAILY_BUDGET_SATS, either deny or reduce to FAUCET_MIN_SATS based on config.
+* Creates a short-lived quote record (quote_id, pubkey, payout_sats, expires_at).
+* Response includes payout_sats and quote_id.
+
+POST /claim/confirm
+
+* Auth required (NIP-98)
+* Input: quote_id
+* Re-check critical guards (pubkey lock, ip lock, budget, balance, quote expiry).
+* Executes LNbits payment.
+* Records claim row with status.
+* Returns success/failure payload.
+
+Notes:
+
+* Confirm must be idempotent: multiple confirms for same quote_id should not pay twice.
+* If confirm is called after quote expiry, return a clean error.
+
+### 5.5 LNbits payout
+
+Backend sends payment to the user’s Lightning address.
+
+Must handle:
+
+* Lightning address validation (basic format and domain resolve).
+* LNURLp resolution: fetch payRequest, then call callback with amount.
+* Handle failures:
+
+  * Mark claim as failed, store error.
+  * Do not consume cooldown if payout did not actually send (configurable, but recommended).
+
+Retries:
+
+* For MVP, 0 retries.
+* For long-term, add a background worker to retry transient failures.
+
+## 6. Nostr data sourcing
+
+### 6.1 Relay list
+
+Backend reads NOSTR_RELAYS from env.
+
+Must query multiple relays in parallel.
+
+### 6.2 Account age
+
+Compute nostr_first_seen_at as earliest observed event timestamp for the pubkey.
+
+Practical strategy:
+
+* Query kinds: 0, 1, 3.
+* Use earliest created_at found.
+* Cache result.
+
+If no events found:
+
+* Treat as new or unknown and deny with a friendly message.
+
+### 6.3 Activity score
+
+Compute a simple score (0 to 100) using cached metrics.
+
+Suggested inputs:
+
+* Has kind 0 metadata.
+* Notes count in last ACTIVITY_LOOKBACK_DAYS.
+* Following count.
+* Followers count (optional if expensive).
+* Optional zap receipts.
+
+The scoring formula must be controlled via env thresholds so it can be tuned as the faucet grows.
+
+## 7. Persistence and Storage
+
+### 7.1 Database
+
+Use Postgres.
+
+Required tables:
+
+* users: pubkey, nostr_first_seen_at, cached metrics, last fetch timestamps.
+* claims: pubkey, claimed_at, payout, ip_hash, status, lnbits identifiers, errors.
+* ip_limits: ip_hash, last_claimed_at, rolling counters.
+* quotes: quote_id, pubkey, payout_sats, expires_at, status.
+* stats_daily (optional): daily totals.
+
+### 7.2 Privacy
+
+* Store ip_hash only (HMAC).
+* Store payout destination as hash.
+* Never log raw Lightning address in plaintext logs.
+
+## 8. Observability
+
+Logging must include:
+
+* Request id
+* pubkey
+* eligibility denial reason
+* payout amount (if eligible)
+* LNbits payment result (success/failure)
+
+Metrics dashboard (optional):
+
+* total claims
+* total paid
+* denial counts by reason
+* payout distribution
+
+## 9. Operational Controls
+
+Environment variables must support:
+
+* FAUCET_ENABLED
+* EMERGENCY_STOP
+* DAILY_BUDGET_SATS
+* MAX_CLAIMS_PER_DAY
+* MIN_WALLET_BALANCE_SATS
+
+Behavior:
+
+* If EMERGENCY_STOP=true, deny all claims with a maintenance message.
+* If wallet balance below MIN_WALLET_BALANCE_SATS, deny claims and encourage deposits.
+
+## 10. API Surface
+
+Public endpoints
+
+* GET /health
+* GET /config
+* GET /stats
+* GET /deposit
+
+Claim endpoints (auth: NIP-98)
+
+* POST /claim/quote
+* POST /claim/confirm
+
+Optional admin endpoints (later)
+
+* GET /admin/claims
+* GET /admin/users
+* POST /admin/ban
+* POST /admin/allow
+
+## 11. Error Handling
+
+All errors must return:
+
+* code (stable string)
+* message (user-friendly)
+* details (optional for debugging)
+
+Common denial codes:
+
+* faucet_disabled
+* emergency_stop
+* insufficient_balance
+* daily_budget_exceeded
+* cooldown_pubkey
+* cooldown_ip
+* account_too_new
+* low_activity
+* invalid_nip98
+* invalid_lightning_address
+* quote_expired
+* payout_failed
+
+## 12. Security Checklist
+
+Minimum required:
+
+* Strict NIP-98 verification (method, url, timestamp, nonce).
+* Nonce replay prevention.
+* IP hashing.
+* Cloudflare or similar rate limiting on claim endpoints.
+* CORS restricted to FRONTEND_URL.
+* No secret keys in frontend.
+
+Nice to have:
+
+* Bot protection (Turnstile) behind a feature flag.
+* VPN/proxy detection behind a feature flag.
+
+## 13. Deployment
+
+* Backend behind a reverse proxy with TLS.
+* TRUST_PROXY=true when behind proxy.
+* Use database migrations.
+
+Recommended:
+
+* Docker compose for backend + Postgres + optional Redis.
+* Separate LNbits deployment.
+
+## 14. Acceptance Criteria
+
+A developer is done when:
+
+* A Nostr user can connect and claim sats successfully to a Lightning address.
+* The faucet enforces cooldowns per pubkey and per IP.
+* The faucet rejects accounts younger than 14 days.
+* The faucet rejects accounts below activity threshold.
+* Payouts are randomized and cannot be rerolled by refreshing.
+* Public page shows deposit address and QR.
+* Public stats show balance and transparency counters.
+* Admin can stop the faucet instantly via env.
+* No raw IPs or LNbits keys leak to the client.