ugly-app 0.1.521 → 0.1.523

package/README.md

@@ -236,7 +236,7 @@ export type AppPages = typeof pages;
 
 ### `bootstrapApp()`
 
-The recommended entrypoint. Handles auth detection, socket creation, optional auto-login through the ugly.bot iframe, and provider wiring.
+The recommended entrypoint. Handles auth detection, socket creation, silent auto-login through the ugly.bot iframe (Mode A only), and provider wiring.
 
 ```tsx
 // client/main.tsx
@@ -272,7 +272,9 @@ bootstrapApp({
 | `strings?` | Localization config — when present, wraps the tree with `<StringsProvider>`. |
 | `keyboard?: false` | Disable the framework `<KeyboardProvider>` wrapper. |
 
-`bootstrapApp` reads `window.__AUTH_TOKEN__` (injected by the server). If absent, it renders unauthenticated and lets the router show `loginFallback` for auth-guarded pages. If present, it connects the socket, mounts `<AppProvider>`, and renders.
+`bootstrapApp` reads `window.__AUTH_TOKEN__` (injected by the server). If absent, it renders unauthenticated and lets the router's per-route auth guard surface the framework's `<AuthRoot>` (Mode A → `<LoginPopup>`; Mode B → magic-link form + optional Google button). If the token is present, it connects the socket, mounts `<AppProvider>`, and renders.
+
+If `bootstrapApp` is loaded at `/auth/magic-link/verify` (Mode B), it renders the `<MagicLinkCallback>` component instead of the regular app shell — that path is the fallback target when the server route is shadowed by a static-assets handler.
 
 ### Routing — `createRouter()`
 
@@ -290,8 +292,8 @@ export const { RouterProvider, RouterView, useRouter } = createRouter({
 
 `createRouter` returns:
 
-- **`RouterProvider`** — props: `children`, `fallback?`, `loginFallback?`, `isAuthenticated?`, `autoLogin?`. Manages route state, browser history, popups, and `<AutoLoginGate>` (silent iframe-based login check against ugly.bot).
-- **`RouterView`** — renders the active page with animated transitions. Props: `durationMs?`, `easing?`, `transitionComponent?` (replaces `ViewFlipper`), `renderPage?` (sync alternative to `allPages` loaders).
+- **`RouterProvider`** — props: `children`, `fallback?`, `isAuthenticated?`. Manages route state, browser history, popups, and the silent auto-login iframe (`<AutoLoginGate>` — only in Mode A; skipped when `window.__UGLY_APP_AUTH_MODE__ === 'self'`). When `isAuthenticated()` returns false and the current route declares `auth: true`, the framework's `<AuthRoot>` is rendered in place of the page — apps cannot override this fallback.
+- **`RouterView`** — renders the active page with animated transitions. Props: `durationMs?`, `easing?`, `transitionComponent?` (replaces `ViewFlipper`), `renderPage?` (sync alternative to `allPages` loaders, called with `RouterStateRaw`).
 - **`useRouter()`** — returns the router context (see below).
 
 ### Page map — `lazyPage` / `lazyPageLoader`
@@ -378,13 +380,13 @@ const {
   showPopup,     // legacy popup API (prefer useRouter().openPopup)
   hidePopup,
   hideAllPopups,
-  runAsync,      // runAsync('label', async () => { ... }) — shows loading overlay
+  runAsync,      // runAsync(label, async () => { ... }, options?) — shows loading overlay while pending
   splashDone,    // mark a splash-screen step complete
   localizer,     // (key, params?) => string — alias for useLocalizer
 } = useApp();
 ```
 
-`useAppOptional()` returns `null` outside the provider; `useLocalizer()` returns a localizer that falls back to identity.
+`useApp` is generic in `TAsyncOptions` so apps can pass an option type through to a custom `loadingOverlay` element. `useAppOptional()` returns `null` outside the provider; `useLocalizer()` returns a localizer that prefers `<StringsProvider>` data, falls back to the `AppProvider` localizer prop, and finally to identity.
 
 ### `Link` component
 
@@ -419,35 +421,59 @@ For pure HTTP (no WebSocket), use `createHttpClient({ requests, token?, baseUrl?
 
 ugly-app uses HttpOnly cookies and server-side JWT injection — no `localStorage`, no client-side token handling.
 
-**Flow:**
+Two modes, picked from the `auth` block in the project's `.uglyapp` config:
+
+- **Mode A — `mode: 'uglybot'`** (default when no `auth` block is present). Auth is delegated to ugly.bot OAuth. AI / email / push proxies bill the end user's ugly.bot credits.
+- **Mode B — `mode: 'self'`**. The app issues its own sessions via magic-link email and/or Google OAuth. AI / email / push proxies bill the developer's ugly.bot account using the project's `AI_PROXY_TOKEN`.
+
+`window.__UGLY_APP_AUTH_MODE__` is injected into every page so client code (incl. `<AuthRoot>` and the router's `<AutoLoginGate>`) can branch correctly.
+
+### Mode A — ugly.bot OAuth (default)
+
+1. Unauthenticated user lands on a page. The router's `<AutoLoginGate>` opens a hidden iframe to `${UGLY_BOT_URL}/iframe-auth` to check for an existing platform session (4 s timeout).
+2. If found, the iframe `postMessage`s an OAuth code back. The client POSTs to `/auth/verify`; the server exchanges it through `uglyBotAuthProvider`, sets the `auth_token` HttpOnly cookie, and reloads.
+3. If not found (or timeout), per-route auth checks surface the framework's `<AuthRoot>` → `<LoginPopup>`, which opens `${UGLY_BOT_URL}/oauth` in a popup window.
+4. On every authenticated page request, the server verifies the cookie token by calling `${UGLY_BOT_URL}/verify`, then injects `window.__AUTH_TOKEN__` into the HTML so the client can attach it to the WebSocket handshake.
 
-1. Unauthenticated user lands on a page; the optional `<AutoLoginGate>` opens a hidden iframe to `https://ugly.bot/iframe-auth` to check for an existing platform session.
-2. If found, the iframe posts an OAuth code back; the client POSTs to `/auth/verify`; the server exchanges it through `uglyBotAuthProvider`, sets the `auth_token` HttpOnly cookie, and the page reloads authenticated.
-3. If not found (or timeout after 4 s), `<RouterProvider>` shows `loginFallback` for auth-required routes. The default fallback is `<LoginPopup>`, which opens `https://ugly.bot/oauth` in a popup window.
-4. On every authenticated request, the server verifies the cookie token by calling `${UGLY_BOT_URL}/verify` and injects `window.__AUTH_TOKEN__` into the HTML so the client can pass it on the WebSocket handshake.
+### Mode B — Self-issued sessions
 
-**Token-in-URL embed mode:** any GET request with `?token=<JWT>` will, if the token verifies against ugly.bot, set the cookie and 302-redirect to the same URL without the token — letting any page be embedded in an iframe.
+When `.uglyapp` sets `auth.mode: 'self'`, `buildAuth()` wires the magic-link provider as primary; if `providers.google.clientId` is configured it adds Google as an extra provider on the same router.
 
-**Built-in routes** (mounted on every app):
+- `<AuthRoot>` renders `<MagicLinkForm>` (plus the Google button when configured) instead of `<LoginPopup>`.
+- The `<AutoLoginGate>` is skipped entirely — the ugly.bot iframe would either silently fail or set a cookie that won't verify against the local session.
+- `POST /auth/magic-link/request` accepts an email, mints a one-time token (default 15 min lifetime, configurable via `auth.magicLinkExpiresMin`), and emails a link.
+- `GET /auth/magic-link/verify?token=…` validates the token, calls `onUserCreate` on first login, sets the session cookie, and redirects.
+- Google login lives at `GET /auth/google/url` + `POST /auth/google/callback` when enabled.
+
+### Token-in-URL embed
+
+Any GET request with `?token=<JWT>` will, if the token verifies, set the cookie and 302-redirect to the same URL without the token parameter — useful for embedding any page in an iframe.
+
+### Built-in routes
+
+Mounted on every app:
 
 | Endpoint | Description |
 |----------|-------------|
 | `POST /auth/verify` | Exchange an OAuth `code` for a session cookie. |
 | `POST /auth/logout` | Clear the cookie. |
-| `GET /auth/token` | Refresh and return the current token (used by clients that need an explicit token). |
+| `GET /auth/token` | Refresh and return the current token. |
 | `GET /auth/url` | Return the OAuth popup URL. |
+| `POST /auth/magic-link/request` | Mode B only — send a magic-link email. |
+| `GET /auth/magic-link/verify` | Mode B only — verify a magic-link token and set the cookie. |
+| `GET /auth/google/url`, `POST /auth/google/callback` | Mode B only — Google OAuth, registered when configured. |
 
-**Custom provider:**
+### Custom provider
 
 ```typescript
 configurator.setAuth({
   verify: async (code) => ({ userId: '...', token: 'platform-issued-jwt' }),
   authUrl: (origin) => `https://my-oauth.example/authorize?origin=${origin}`,
-  registerRoutes: (router) => { /* optional extra routes */ },
+  registerRoutes: (router, { db, onUserCreate }) => { /* extra routes */ },
 });
 ```
 
-**Server-side helpers** (`ugly-app`):
+### Server-side helpers (`ugly-app`)
 
 - `verifyToken(token)` — verifies a token against ugly.bot and returns the `userId`.
 - `getRequestUser(req)` — synchronous decode of the per-project `UGLY_PROJECT_TOKEN` cookie set by ugly.bot's wake-on-traffic gate. Returns `{ userId } | null` without a network round-trip; safe to use as the primary auth check in deployed-app handlers.

package/dist/cli/version.d.ts

@@ -1,2 +1,2 @@
-export declare const CLI_VERSION = "0.1.521";
+export declare const CLI_VERSION = "0.1.523";
 //# sourceMappingURL=version.d.ts.map

package/dist/cli/version.js

@@ -1,3 +1,3 @@
 // Auto-generated by prebuild — do not edit manually
-export const CLI_VERSION = "0.1.521";
+export const CLI_VERSION = "0.1.523";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugly-app",
-  "version": "0.1.521",
+  "version": "0.1.523",
   "type": "module",
   "main": "./dist/server/index.js",
   "exports": {

package/src/cli/version.ts

@@ -1,2 +1,2 @@
 // Auto-generated by prebuild — do not edit manually
-export const CLI_VERSION = "0.1.521";
+export const CLI_VERSION = "0.1.523";