# Platform-hosted apps (AI builders & preview hosts)

**Audience:** AI agents when the app runs on a **platform-hosted URL** (Lovable, Base44, Vercel preview, etc.).

**Canonical source:** [SKILL.md](https://www.secure-flows.com/ai/secureflows-integration/SKILL.md) — **Platform-hosted apps**.

## Minimal human prompt (nothing else)

```
Use secureFlows for auth and data storage (read https://www.secure-flows.com/ai/secureflows-integration/SKILL.md).
Use: workspace = <WORKSPACE>, appId = <APP_ID>
```

The human does **not** add stack, auth, or callback instructions. The agent reads SKILL.md and:

1. Parses `workspace` and `appId` from the two lines above.
2. **Infers client stack** from the project (React on Lovable/Base44 by default).
3. Implements the matching path in SKILL.md (**React starter**, **plain JS**, or **Flutter**).

## Auth (stable hosted login)

| Step | What happens |
|------|----------------|
| 1 | App restores an existing session token if present |
| 2 | No token → show **Continue with secureFlows** |
| 3 | Click → redirect to secureFlows hosted login |
| 4 | Browser returns to `https://<host>/callback?sessionToken=…` |
| 5 | `SecureFlowsCallback` stores token → `location.replace("/")` |
| 6 | App loads session payload from the stored token |
| 7 | App calls **`GET /api/v1/sessions/identity`** (or **`sf.fetchSessionIdentity`**) and shows **email** next to **Sign out** |

Same flow in preview and published app — **no popup**.

**Two valid React paths on Lovable/Base44:**

| Path | Auth UX | Package |
|------|---------|---------|
| **Proven plain redirect** (recommended on AI builders) | Auto-redirect when no token on guarded routes; explicit sign-out | Hand-rolled — no `secureflows-js` |
| **React starter + SDK** | Explicit **Continue with secureFlows** CTA; signed-in email in header | `secureflows-js` ≥ 0.1.13 |

See **`SKILL.part-00-essentials.md`** (hand-rolled redirect) for react-router and TanStack Router
examples. Same-frame `window.location` works in preview iframes.

If every navigation attempt is blocked (SDK path), `secureflows-js` rejects with `HostedLoginNavigationError`.
Show that message, stop "Redirecting...", keep the same secureFlows CTA. Do **not** switch to popup
delivery or `window.top` breakout as a workaround.

## Non-negotiable

1. Copy starter files (`main.tsx`, `SecureFlowsCallback.tsx`, `secureFlowsSession.tsx`, `callbackUri.ts`).
2. **No `RequireAuth`** — delete platform-generated auth wrappers.
3. **No Supabase** — secureFlows only.
4. **Redirect URIs:** use the published/preview host constant, or `window.location.origin` on plain redirect when that URL is allowlisted — not an unrelated editor iframe origin.
5. Allowlist `https://<preview-deployment-host>/callback` in dashboard.
6. React on Lovable — not Flutter Web. Plain JS / Flutter only when project already uses that stack (see SKILL.md **Choose client stack**).

## Testing

- One incognito window; test on **preview deployment URL**.
- Starter: `templates/web-app-secureflows/` — local demo: `usecases/static-web-js/`.