# Lovable Account Registration & Session Management

## Context

Lovable.dev — AI app builder. The `lovable2api` gateway (localhost:8877) proxies build requests through authenticator browser sessions. Each session requires a valid Lovable JWT obtained by logging into lovable.dev.

The gateway stores sessions in DPAPI-encrypted `.gateway-secrets.dpapi` (Windows only). Session registration is done via `POST /v1/session` with a `lovable_token` JWT.

## Registration Flow

### Email Registration

**URL:** `https://lovable.dev/signup`

**Step 1 — Email input:**
- Form shows email textbox + "Continue" button
- If email doesn't exist: shows "No account found. Sign up or try another email."
  - Transitions to password input page with password requirements display
- If email exists: redirects to login page

**Step 2 — Password + Turnstile:**
- Password requirements: min 8 characters, must contain a number (0-9)
- "Password meets all requirements" shown when valid
- Cloudflare Turnstile challenge (checkbox) appears below password
- "Create your account" button disabled until captcha passed

**Step 3 — Turnstile Captcha:**
- Sitekey: `0x4AAAAAAChnKAZBY0iFpFHC` (visible in page source / Turnstile iframe URL)
- **⚠️ Turnstile consistently blocks Chrome DevTools Protocol (CDP) automation**
  - Sign: iframe URL contains `/auto/fbE/failure_retry/normal` after click, shows "Сбой проверки" (Verification failure)
  - Turnstile detects `navigator.webdriver`, missing `chrome.runtime`, and other CDP traces
  - Even after manual checkbox click → `failure_retry` → captcha never validates
- After registration: may send verification email (depends on account age/domain)

### Social Auth

- **Google / GitHub / Apple** buttons on signup form
- Open OAuth popup — **may bypass Turnstile** if the provider's popup has its own auth flow
- **⚠️ Google OAuth without saved session**: If Chrome has no Google login cached, the popup lands on email input page (not account picker) — requires full Google credentials entry
- **⚠️ Google OAuth from CDP Chrome**: Google's signup flow detects CDP automation. Creating a new Google account via the "Создать аккаунт" link fails with **"Не удалось создать аккаунт Google"** (Could not create Google account) — Google's anti-automation rejects headless browsers even after completing all form steps (name, birthday, gender, username, password). Existing Google sessions may still work.
- **⚠️ GitHub OAuth → DataDome CAPTCHA (2026-08-09)**: GitHub's signup page (`github.com/signup`) triggers DataDome CAPTCHA ("Доступ временно ограничен") when accessed from a CDP-controlled browser. The DataDome block is separate from Lovable's Turnstile — it's GitHub's own anti-bot layer. Existing GitHub sessions may bypass this; new signup from CDP Chrome is blocked.

## Gateway Session Management

### Register a Lovable Session

```bash
curl -X POST http://localhost:8877/v1/session \
  -H "X-API-Key: [REDACTED]" \
  -H "Content-Type: application/json" \
  -d '{"lovable_token": "[REDACTED-JWT]..."}'
```

Response on success:
```json
{"ok": true, "session": {"id": "...", "label": "", "ready": true, ...}, "upstream": {...}}
```

**What the gateway does with the JWT:**
1. Validates token is a JWT (starts with `eyJ`, 3 dot-separated parts)
2. Checks JWT expiry timestamp (`_jwt_exp_timestamp` — parses base64 payload)
3. Encrypts and stores session in `.gateway-secrets.dpapi`
4. Marks session as `enabled: true, ready: true`
5. Routes subsequent `POST /v1/chat` / `POST /v1/create-project` through this session

### What V1 Session Endpoint Accepts

| Field | Description |
|-------|-------------|
| `lovable_token` | Lovable JWT (required). Also `token` alias. |
| `session_ref` | Reference to an existing session to update. Optional. |
| `projectId` / `workspaceId` | Optional context scoping. |
| `email` | Optional — used for routing on upstream. |

### JWT Format

- Standard JWT: `eyJ...` base64-url encoded header.payload.signature
- Expiry embedded in payload: `{"exp": 1722748800, ...}`
- Gateway auto-disables sessions where `exp < now + 30s`
- Session shows `disabled_reason: "jwt_expired"` when expired

### JWT Extraction from Logged-In Browser

After a successful login on lovable.dev:

**From localStorage:**
```javascript
// Execute in browser console:
const token = [REDACTED]'lovable_token') || localStorage.getItem('token');
console.log(token);
```

**From cookies:**
```javascript
// Check cookies:
document.cookie.split('; ').filter(c => c.includes('lovable_token') || c.includes('token'));
```

**From network requests (DevTools Network tab):**
- Filter by `lovable.dev/api`
- Look for `Authorization: Bearer eyJ...` in request headers
- Also check `X-Lovable-Token` or similar custom headers

**From Chrome DevTools MCP:**
```javascript
// After page is loaded with logged-in session:
const token = await page.evaluate(() => localStorage.getItem('lovable_token'));
// Or via mcp__chrome_devtools__evaluate_script
```

### Session Lifecycle

```
Register JWT → Session ready, pool auto-selects
     ↓
JWT expires (~1-7 days, checked by _jwt_exp_timestamp)
     ↓
Session disabled_reason = "jwt_expired"
     ↓
Need fresh JWT → re-login → POST /v1/session again
```

- Gateway checks expiry with `_session_ready()` helper: `exp > now + 30s`
- Cooldowns: `SESSION_COOLDOWN_SECONDS=300`, `SESSION_AUTH_COOLDOWN_SECONDS=900`
- Failed builds recorded against session; after 14+ failures with no success, session pool shows 0 ready

### Checking Session Status

```bash
curl http://localhost:8877/v1/status -H "X-API-Key: [REDACTED]"
```

Key session fields:
- `enabled`: true/false (gateway-level toggle)
- `ready`: true/false (JWT valid + upstream ready)
- `disabled_reason`: "jwt_expired" | "" | null
- `last_success_at`: ISO timestamp of last successful build
- `failed_generations`: count of failed build attempts

### List Sessions

```bash
curl http://localhost:8877/v1/sessions -H "X-API-Key: [REDACTED]"
```

### Delete a Dead Session

```bash
curl -X DELETE http://localhost:8877/v1/sessions/<session_id> \
  -H "X-API-Key: [REDACTED]"
```

## Known Issues & Pitfalls

1. **CDP-can't-register**: Cloudflare Turnstile on lovable.dev/signup detects Chrome DevTools Protocol and rejects all captcha attempts. Even clicking the checkbox manually via CDP results in `failure_retry`. This is a Turnstile anti-bot measure, not a misconfiguration.
2. **All three OAuth providers blocked via CDP (2026-08-09)**: GitHub signup triggers DataDome CAPTCHA, Google's new-account creation detects automation and returns "Не удалось создать аккаунт", Apple likely similar. The only CDP path is using an already-logged-in browser profile with existing sessions. Fresh account creation via any OAuth provider from headless CDP Chrome is blocked.
3. **JWT expiry**: Lovable JWTs expire. Sessions die silently unless monitored via `/v1/status`. The gateway checks `exp` claim — tokens expiring within 30s are treated as dead.
4. **No API key in JWT**: Lovable doesn't issue API keys — it's web-session-only. The gateway's `lovable_token` IS the web JWT.
5. **No public registration endpoint**: Lovable does NOT offer a public API for account registration. All registration goes through the web form with Turnstile.
6. **Email verification**: If the registration succeeds but email verification is required, the account won't generate valid build tokens until verified. Temp-mail domains may be blocked.
7. **Builder Engine v2 fallback**: When no Lovable session is available, the local `builder_engine.py` can still generate static sites (HTML/CSS) with themed templates (premium, light, bold, neon, glassmorphism). 15+ sites generated, 5 themes, 5 data configs available as of 2026-08-04.