# Northstar Login A polished React authentication portal for Northstar with Google OAuth, password login, email magic links, account verification, and session-aware protected access. ## Masterplan - Provide a focused, trustworthy sign-in experience for Northstar users. - Support multiple authentication preferences: Google, email/password, and passwordless magic links. - Let new users create an account with an email verification code. - Restore authenticated sessions automatically and protect the `/welcome` route. - Maintain a lightweight, responsive UI with persistent light/dark theme choice. ## Tech Stack & Architecture - **React + TypeScript**: Application UI and client-side state. - **React Router (`react-router-dom`)**: Browser-history routing for auth pages and protected welcome page. - **Tailwind CSS v4**: Utility styling through `@import "tailwindcss"` in `src/styles/main.css`. - **Lucide React**: Icons used throughout auth controls, notices, and branding. - **GenMB Auth SDK**: Injected by `index.html`; exposed globally as `window.genmb.auth`. - **No app-owned backend**: Authentication requests, OAuth popup/redirect behavior, sessions, magic-link token verification, OTP verification, and password reset are managed by the injected GenMB SDK and its `/api/auth/...` endpoints. Architecture and state: - `src/main.tsx` mounts `` inside `BrowserRouter` and imports global CSS. - `src/App.tsx` owns session bootstrap state: - Calls `window.genmb.auth.ready()` once on mount. - Reads the active user with `getUser()`. - Subscribes through `onAuthStateChange()` to keep `user` current. - Restores the persisted `northstar-theme` setting before the app renders routes. - Each page owns its local form state, validation messages, loading state, and request lifecycle. - `ToastProvider` is the global notification mechanism. Use `useToast()` only below this provider. - `AuthShell` wraps every page and provides shared branding, responsive two-column layout, theme toggle, and footer. - The GenMB SDK automatically consumes `?magic_token=...` during `auth.ready()`, then cleans the token from the URL. ## File Structure ```text index.html # HTML metadata and injected GenMB authentication SDK. src/main.tsx # React entry point; mounts App under BrowserRouter. src/App.tsx # Route table, initial auth/session hydration, theme restoration. src/components/AuthShell.tsx # Shared branded layout, dark-mode toggle, security marketing panel. src/components/ToastProvider.tsx# Toast context, 5-second auto-dismiss notifications, useToast hook. src/components/ui/Button.tsx # Shared button variants and loading spinner behavior. src/components/ui/Card.tsx # Shared bordered card container. src/lib/utils.ts # cn() utility for conditionally joining Tailwind class names. src/pages/LoginPage.tsx # Google, password, and magic-link sign-in flows. src/pages/SignupPage.tsx # Two-step signup: account details then six-digit email verification. src/pages/ResetPasswordPage.tsx # Password-reset email/code request entry point. src/pages/WelcomePage.tsx # Session-protected authenticated confirmation and sign-out. src/styles/main.css # Tailwind theme token mapping, light/dark variables, base styles. src/types/genmb.d.ts # Type declarations for window.genmb.auth and GenMBUser. ``` ## Key Features ### Authentication methods `src/pages/LoginPage.tsx` supports: - **Google OAuth** via `window.genmb.auth.signIn()`. - The SDK opens a popup and falls back to a full-page redirect when popups are blocked. - A `null` result is treated as a closed/cancelled sign-in, not a successful login. - **Email/password login** via `signInWithPassword(email, password)`. - Client validation requires a basic valid email format and password length of at least 8 characters. - **Magic link login** via `sendMagicLink(email)`. - Displays inline confirmation after dispatch. - Verification happens automatically during `auth.ready()` when the SDK finds `magic_token` in the URL. ### Signup and verification `src/pages/SignupPage.tsx` is a two-step state machine: 1. `details`: collect optional name, email, and password. 2. `verify`: collect exactly six numeric digits and call `verifySignUp(email, code)`. Requirements: - Require valid email and passwords of at least 8 characters before calling `signUp`. - Preserve submitted email while moving between steps. - The “Edit account details” button returns to `details` without discarding entered values. - Successful verification creates a session and navigates to `/welcome`. ### Password reset `src/pages/ResetPasswordPage.tsx` currently implements the **reset request** step: - Calls `requestPasswordReset(email)`. - Shows a generic success message to avoid confirming whether an account exists. - `window.genmb.auth.confirmPasswordReset(email, code, newPassword)` is typed in `src/types/genmb.d.ts` but is **not yet surfaced by a UI route**. A future completion page should collect the emailed code and new password, then call it. ### Session and route protection - `/welcome` receives `user` and `loading` from `App.tsx`. - While session initialization is pending, it displays a skeleton card. - Unauthenticated visitors are redirected to `/login`. - `signOut()` relies on the auth-state subscription to clear `user`; once cleared, the wildcard navigation behavior resolves to `/login`. - The wildcard route redirects unknown routes to `/welcome` for active users or `/login` otherwise. ### Auth model ```ts type GenMBUser = { id: string; email: string; name: string; picture: string; }; ``` ### GenMB SDK surface used or available ```ts auth.ready(): Promise auth.signIn(): Promise auth.sendMagicLink(email): Promise<{ success: boolean; data?: unknown }> auth.signUp(email, password, name?): Promise<{ success: boolean; data?: unknown }> auth.verifySignUp(email, code): Promise auth.signInWithPassword(email, password): Promise auth.requestPasswordReset(email): Promise auth.confirmPasswordReset(email, code, newPassword): Promise<{ success: boolean; data?: unknown }> auth.signOut(): Promise auth.getUser(): GenMBUser | null auth.onAuthStateChange(callback): () => void ``` ## Design Guidelines - **Visual direction:** Calm, high-trust security portal with rounded cards, restrained shadows, blue primary actions, and subtle security-themed gradients. - **Typography:** `Inter, ui-sans-serif, system-ui, sans-serif`; large, tightly tracked headings and compact readable form text. - **Light theme:** Off-white blue-tinted background, white cards, deep navy text, primary blue `hsl(221 83% 53%)`. - **Dark theme:** Near-black navy background, dark-blue cards, light text, brighter blue primary `hsl(217 91% 60%)`. - **Semantic colors:** Use existing tokens—`primary`, `success`, `info`, `destructive`, `muted`, `border`, `ring`—rather than literal colors. - **Radius:** Default visual radius is `0.625rem`; cards use `rounded-lg`, feature panel uses `rounded-xl`. - **Responsive layout:** `AuthShell` is single-column on small screens. The informational security panel appears below the auth card, then shifts to the left side in a two-column layout at `lg`. - **Accessibility:** Preserve labels, `aria-invalid`, error descriptions, live-toast announcements, focus rings, and disabled/loading behavior. ## App Flow 1. Visiting `/`, an unknown path, or a completed auth callback resolves through the wildcard route: - authenticated user → `/welcome` - no active user → `/login` 2. On first load, `App.tsx` waits for `auth.ready()`, which restores sessions and may verify a magic-link token. 3. On `/login`, users can: - sign in with Google; - sign in with email/password; - send a magic link; - navigate to `/signup` or `/reset-password`. 4. On `/signup`, users submit details, receive a six-digit email code, verify it, and land on `/welcome`. 5. On `/reset-password`, users request reset instructions. The code-confirmation/new-password interface remains to be implemented. 6. On `/welcome`, authenticated users see account confirmation and can sign out. 7. Theme toggling adds/removes `.dark` on `` and stores `northstar-theme` in `localStorage`. Important edge cases: - Google sign-in can return `null` when cancelled or when the SDK transitions to redirect flow. - Magic-link users return through a URL token; do not manually parse or retain this token in page state. - Prevent duplicate requests by retaining the existing `loading`/`pending` disabled states. - Do not assume `user.name` is populated; use `user.name || user.email` or the existing “there” fallback. ## Conventions - **Components:** Default-export page and UI components. Keep shared presentation components under `src/components/`; page-specific state stays in `src/pages/`. - **Naming:** PascalCase for React components and files; camelCase for variables, handlers, and utility functions. - **Styling:** Use Tailwind utility classes and semantic theme tokens from `src/styles/main.css`. Use `cn()` from `src/lib/utils.ts` when composing conditional class names. - **Buttons:** Use `src/components/ui/Button.tsx` rather than raw buttons for interactive actions. Pass `loading` for async submissions; it sets `disabled` and `aria-busy`. - **Cards:** Use `Card` for the auth panel’s standard border, background, padding, and shadow. - **Feedback:** Use `useToast().showToast(type, title, description?)` for request outcomes. Use inline messages for field-specific errors or persistent next-step notices. - **Routing:** Add routes in `src/App.tsx`. Public auth screens should use `AuthShell`; protected screens must receive or independently resolve session state and redirect unauthenticated users. - **Metadata:** Each page updates `document.title` and the existing description meta tag in a mount-only `useEffect`. - **New auth feature workflow:** 1. Add the page under `src/pages/`. 2. Wrap content in `AuthShell` and `Card`. 3. Add client validation before SDK calls. 4. Add route in `src/App.tsx`. 5. Use typed methods from `window.genmb.auth` as declared in `src/types/genmb.d.ts`. 6. Provide loading, error, cancellation, and success states; avoid exposing account-existence details in recovery flows. ## Platform (GenMB) This app is built and hosted on GenMB. **Runtime:** Browser sandbox (iframe) or Cloud Run. No Node.js server — all code runs client-side unless `backend/` exists. **Dependencies:** CDN-only (esm.sh, cdn.tailwindcss.com, unpkg). Use ES module imports with full CDN URLs. No `npm install` at runtime. **Entry point:** `index.html` must include all CDN script tags. Tailwind via CDN with inline config. **Built-in services (relative API paths only, never hardcode domains):** - `/api/ai/completion` — AI proxy | `/api/data/{appId}/*` — PostgreSQL (DataConnect SDK) - `/api/storage/{appId}/*` — File uploads (GCS) | `/api/auth/google/*` — Google OAuth - `/api/contact/submit` — Contact form | SDKs: `window.genmb.db`, `.storage`, `.auth` **File structure:** `index.html` (entry), `src/` (source), `styles/` (CSS), `backend/` (optional FastAPI), `CLAUDE.md` (this file). **Cannot:** Install npm packages at runtime, access filesystem, make direct server-side calls from frontend, modify infra.