# Gatekeeper — Automatic OTP Login Secure authentication UI with password, Google, magic-link, email OTP signup, and password-reset flows powered by the injected GenMB Auth SDK. ## Masterplan - Provide a polished, low-friction account access experience for users who need secure email-based authentication. - Support multiple entry methods: password sign-in, Google sign-in, passwordless magic links, account creation with generated OTPs, and OTP-based password resets. - Make auth status and failures understandable through inline validation, loading states, and toast feedback. - Keep all authentication authority in the GenMB capability; this React app is a client UI and does not generate, store, or validate OTPs itself. ## Tech Stack & Architecture - **React 19 + TypeScript** application bootstrapped in `src/main.tsx`. - **Vite** build/dev tooling configured in `vite.config.ts`. - **React Router DOM** using `HashRouter` in `src/app.tsx`. - Routes use hash URLs such as `#/login` and `#/account`. - Do not replace with `BrowserRouter` unless hosting rewrite rules are added. - **Tailwind CSS v4** imported with `@import "tailwindcss"` in `src/styles/main.css`. - Theme tokens are CSS variables mapped into Tailwind utilities via `@theme inline`. - **Lucide React** supplies all icons. - **GenMB Auth SDK** is injected directly in `index.html` and exposed as `window.genmb.auth`. - It handles session restoration, Google OAuth, magic links, password accounts, OTP verification, resets, and sign-out. - `src/types/genmb.d.ts` defines the SDK’s client-side TypeScript contract. - **No application backend/API routes exist.** Authentication requests are made by the injected SDK, not by React fetch calls. - Global auth state lives in `AppRoutes` (`src/app.tsx`) as `GenMBUser | null`. - `auth.ready()` restores/checks the session before routes render. - `onAuthStateChange()` keeps React state synchronized with the SDK. - Pages receive the current user and callbacks as props rather than using a global state library. - Local UI state remains inside pages: - `src/pages/login-page.tsx` owns active auth view, fields, validation errors, and pending action. - `src/pages/account-page.tsx` owns sign-out pending state. - `ToastProvider` wraps the full app in `src/app.tsx`; call `useToast()` only below that provider. ## File Structure ```text index.html # Vite HTML shell and injected GenMB Auth SDK capability. package.json # Runtime/build dependencies and scripts. vite.config.ts # Vite configuration. src/ ├── main.tsx # Finds #root, renders React StrictMode, imports global CSS. ├── app.tsx # Auth initialization, session subscription, router, guards, provider. ├── pages/ │ ├── login-page.tsx # All sign-in, signup OTP, magic-link, and reset UI/actions. │ └── account-page.tsx # Authenticated account summary and sign-out controls. ├── components/ │ ├── layout/ │ │ └── auth-shell.tsx # Shared Gatekeeper header, nav, footer, and page framing. │ └── ui/ │ ├── button.tsx # Styled variants/sizes with accessible loading state. │ ├── text-field.tsx # Labeled input with hint/error ARIA wiring. │ └── toaster.tsx # Toast context, timed notifications, and useToast hook. ├── hooks/ │ └── use-page-meta.ts # Updates title and meta description per page. ├── lib/ │ ├── auth.ts # Safe GenMB Auth accessor and SDK-error-to-copy mapping. │ └── utils.ts # cn(): clsx plus tailwind-merge. ├── styles/ │ └── main.css # Tailwind import, light/dark tokens, global styles, animations. └── types/ └── genmb.d.ts # Global GenMB SDK, user, and auth error declarations. ``` ## Key Features ### Authentication methods `src/pages/login-page.tsx` supports these SDK methods: | User action | SDK call | Result | |---|---|---| | Google sign-in | `getAuth().signIn()` | Opens OAuth popup or redirect fallback; successful user navigates to `/account`. | | Password sign-in | `signInWithPassword(email, password)` | Authenticates an existing account. | | Magic-link sign-in | `sendMagicLink(email)` | Sends a secure email link and shows the `magic-sent` confirmation view. | | Sign up request | `signUp(email, password, name?)` | Requests an email-delivered 6-digit signup OTP. | | Confirm signup | `verifySignUp(email, code)` | Consumes the 6-digit OTP, creates/signs in the account, then navigates to `/account`. | | Password reset request | `requestPasswordReset(email)` | Requests a reset OTP by email. | | Confirm password reset | `confirmPasswordReset(email, code, newPassword)` | Applies a new password after OTP confirmation. | | Sign out | `signOut()` | Ends the SDK session and clears app user state. | ### OTP behavior - OTPs are **not generated in browser code**. The GenMB auth service generates and emails them. - Signup and reset code inputs accept only exactly six digits (`/^\d{6}$/`). - Never add a client-side “auto-fill generated OTP” value: users must enter codes received through their email. - Account messaging describes codes as auth-service-generated rather than claiming the app itself secures or stores them. ### Validation and feedback - Email validation uses `emailPattern` in `src/pages/login-page.tsx`. - New passwords and signup passwords require at least 8 characters. - Validation errors are supplied through `TextField` so `aria-invalid` and `aria-describedby` stay correct. - Async actions set a shared `pendingAction`; `busy` prevents conflicting auth actions while a request is active. - Each async action creates a loading toast then updates that same toast to success, info, or error. - SDK errors must pass through `getAuthErrorMessage()` in `src/lib/auth.ts` for user-safe copy. ### Auth state and route guards - `AppRoutes` blocks route rendering while `auth.ready()` checks session state. - If the capability is absent or initialization fails, render the retryable `AuthUnavailable` state. - `LoginPage` redirects authenticated users to `/account`. - `AccountPage` redirects unauthenticated users to `/login`. - The Account navigation link remains visible when signed out, but the route guard prevents account data from rendering. ### Auth SDK surface Declared in `src/types/genmb.d.ts`: ```ts ready(): Promise signIn(): Promise sendMagicLink(email): Promise<{ success: boolean; data: unknown }> signUp(email, password, name?): Promise<{ success: boolean; data: unknown }> verifySignUp(email, code): Promise signInWithPassword(email, password): Promise requestPasswordReset(email): Promise confirmPasswordReset(email, code, newPassword): Promise<{ success: boolean; data: unknown }> signOut(): Promise getUser(): GenMBUser | null isAuthenticated(): boolean onAuthStateChange(callback): () => void ``` `GenMBUser` contains `id`, `email`, `name`, and `picture`. The current account page uses name/email only. ## Design Guidelines - Product name: **Gatekeeper**. - Style: restrained security-product interface with white/light cards, thin borders, rounded corners, compact shadows, and blue primary actions. - Typography: `Inter` when installed; otherwise system sans-serif fallback defined in `src/styles/main.css`. - Use semantic Tailwind tokens, not hardcoded colors: - `background`, `foreground`, `card`, `border`, `muted` - `primary` for secure/positive primary actions - `destructive` only for harmful actions or errors - Theme supports system dark mode using `prefers-color-scheme`; new UI must work in both token sets. - Default radius is `0.65rem`; follow existing `rounded-md` controls and `rounded-lg` cards. - Layout widths: - Shared chrome max width: `max-w-6xl`. - Login/auth content is narrow and form-focused. - Account content max width: `max-w-4xl`. - Responsive behavior: - Start mobile-first with 320px minimum width. - Header/footer and account controls stack on small screens. - Account security cards become two columns at `md`. - Maintain visible keyboard focus rings using `focus-visible:ring-*`. - Buttons should use the shared `Button`; loading state hides visible contents, keeps layout stable, and adds a screen-reader label. - Use `content-enter` for page main content and `toast-enter` only for notifications. ## App Flow 1. Application loads through `src/main.tsx`. 2. `AppRoutes` calls `getAuth().ready()` before showing routes. - Existing sessions populate `user`. - Magic-link tokens are processed by the injected SDK during `ready()`. - SDK initialization failure displays the retry screen. 3. Root and unknown hash routes redirect to `/login`. 4. On `/login`: - Authenticated users are immediately redirected to `/account`. - Users choose password or magic-link mode, Google, signup, or reset flows. - Signup and reset flows preserve the entered email while progressing to OTP verification. 5. A successful sign-in, signup verification, or Google authentication calls `onAuthenticated(user)` and navigates to `/account`. 6. On `/account`: - Missing user redirects to `/login`. - Sign-out calls SDK `signOut()`, clears app state, notifies the user, and navigates to `/login`. Key edge cases: - `signIn()` returning `null` is treated as cancelled, not successful. - Popup-blocked Google auth may redirect the full page; do not assume the current component remains mounted. - SDK absence is recoverable through **Try again** rather than a blank/crashed app. - Duplicate submissions are prevented through pending/loading state. - Magic-link completion can return on a fresh app load; session initialization, not the original form state, establishes the logged-in user. ## Conventions - Use lowercase kebab-case filenames: `login-page.tsx`, `auth-shell.tsx`. - Use PascalCase React components and `type` aliases for component props. - Prefer default exports for pages/layout components, matching existing imports. - Use `cn()` from `src/lib/utils.ts` whenever conditional Tailwind classes are needed. - Use Tailwind utility classes and design tokens; do not introduce CSS modules or inline style objects. - Keep page metadata current with `usePageMeta(title, description)`. - Access the capability only via `getAuth()`; do not directly reference `window.genmb` in page components. - Map caught auth errors with `getAuthErrorMessage(error)`. - Keep SDK interactions asynchronous, toast-backed, and protected by appropriate loading state. - Do not persist passwords, OTPs, users, or sessions in `localStorage`; session lifecycle belongs to the auth SDK. ### Adding a page or feature 1. Add the page in `src/pages/-page.tsx` and call `usePageMeta`. 2. Add its route in `src/app.tsx` inside `AppRoutes`. 3. Use `AuthShell` for normal application pages and select the correct `activePage` value, extending its union/navigation only when needed. 4. For protected features, accept `user` from `AppRoutes` and redirect with `` if absent. 5. Reuse `Button`, `TextField`, and `useToast` instead of duplicating control, validation, or notification behavior. 6. If new auth SDK functionality is introduced, update `src/types/genmb.d.ts` and centralize its error copy in `src/lib/auth.ts`. ## 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.