From 775fb1594c2543b1ed6781cd4f7a702f4c5d5ca4 Mon Sep 17 00:00:00 2001 From: gb_flea Date: Mon, 1 Jun 2026 15:44:11 +0000 Subject: [PATCH 1/2] GRO-1867: bridge Better Auth session to CustomerPortal MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a third initialisation path to src/portal/CustomerPortal.tsx so real customers authenticated via Authentik SSO can reach /portal without being bounced back to /login. After the existing impersonation (?sessionId=) and dev-mode (localStorage dev-user) paths, the portal now: 1. Calls GET /api/auth/get-session (credentials: include) to detect an active Better Auth session. 2. If the user is a non-staff customer, POSTs /api/portal/session-from-auth (the endpoint shipped by GRO-1866) to mint a portal session. 3. Stores the returned sessionId in portalSessionId state and threads it through renderSection -> sections so all /api/portal/* calls include the X-Impersonation-Session-Id header. 4. On 404 (no client row), renders a friendly "Portal access not configured" card with a Sign out button instead of looping back to /login. On 401/network error, falls through to the existing /login redirect guard. The bridge skips when impersonation or dev-user is active and when the Better Auth user is staff (App.tsx already routes staff to /admin). The impersonation banner remains gated on session?.status === "active", so the SSO-bridged session does not show staff chrome. Tests: - 4 new vitest cases in src/__tests__/portal.test.tsx cover the success, 404 fallback, missing-Better-Auth-session, and staff-role paths. - pnpm vitest run src/__tests__/portal.test.tsx -> 18 passed - pnpm typecheck -> clean UAT_PLAYBOOK.md: adds §5.25 (TC-WEB-5.25.1 - TC-WEB-5.25.11) covering the new flow end-to-end on UAT. Co-Authored-By: Paperclip --- UAT_PLAYBOOK.md | 24 +++++ src/__tests__/portal.test.tsx | 161 ++++++++++++++++++++++++++++++++++ src/portal/CustomerPortal.tsx | 106 ++++++++++++++++++++-- 3 files changed, 286 insertions(+), 5 deletions(-) diff --git a/UAT_PLAYBOOK.md b/UAT_PLAYBOOK.md index 3b009ae..e6dbc30 100644 --- a/UAT_PLAYBOOK.md +++ b/UAT_PLAYBOOK.md @@ -347,6 +347,30 @@ export const { signIn, signOut, useSession, changePassword } = authClient; | TC-WEB-5.24.12 | No PII in analytics payloads | Fire each event and inspect detail object | Payload contains only: step, flow, timestamp — no names, emails, phone numbers, or pet names | | TC-WEB-5.24.13 | No-op safe | Trigger analytics with window.dispatchEvent blocked (e.g. CSP) | No error thrown; booking flow completes normally | +### 5.25 Customer Portal — Better Auth SSO Bridge (GRO-1867) + +These cases cover the `CustomerPortal` initialisation path that bridges an Authentik / Better Auth session into a portal session via `POST /api/portal/session-from-auth`. The bridge runs after the URL-impersonation (`?sessionId=`) and dev-user paths have been ruled out. + +**Pre-conditions:** + +- UAT is configured with Authentik SSO and the `seed-uat-passwords` Secret in `groombook-uat` provides the seeded customer credentials (`uat-seed-password-source` memory). +- `POST /api/portal/session-from-auth` from [GRO-1866](https://paperclip.farhoodlabs.com/GRO/issues/GRO-1866) is deployed on UAT. +- Clear cookies and localStorage between cases unless otherwise noted. + +| # | Scenario | Steps | Expected | +|---|----------|-------|----------| +| TC-WEB-5.25.1 | Authenticated customer reaches portal dashboard | 1. From clean state, navigate to UAT `/login`. 2. Click "Sign in with SSO" and complete Authentik flow with a seeded **customer** identity. 3. After callback, land on `/`. | Portal dashboard renders. No redirect to `/login`. No impersonation banner. Top-right greeting reads "Hi, <FirstName>". | +| TC-WEB-5.25.2 | Bridge call sequence | Repeat TC-WEB-5.25.1 with DevTools → Network open and the **All** tab filtered to `/api/`. | In order: `GET /api/auth/get-session` → 200. `POST /api/portal/session-from-auth` → 201 with body `{ sessionId, clientId, clientName }`. | +| TC-WEB-5.25.3 | Subsequent portal calls use the bridged session ID | After TC-WEB-5.25.1 succeeds, navigate to **Appointments**, **My Pets**, **Billing**, **Settings**. Inspect any `/api/portal/*` request in DevTools → Network. | Each portal API call carries an `X-Impersonation-Session-Id` header whose value equals the `sessionId` returned by `session-from-auth` (not a URL-param value). Each call returns 200 (or 404 for genuinely empty collections), never 401. | +| TC-WEB-5.25.4 | No impersonation chrome for the customer's own session | After TC-WEB-5.25.1, scan the portal UI. | No amber border around the page. No "STAFF VIEW" watermark. No "End Impersonation" button in the sidebar. The customer is themselves; only impersonation sessions started via `?sessionId=` show the banner. | +| TC-WEB-5.25.5 | 404 fallback for authenticated user with no client record | 1. Sign in via SSO with an Authentik account whose email is **not** present in `clients`. 2. Land on `/`. | `POST /api/portal/session-from-auth` returns 404. The portal renders a centred card titled **"Portal access not configured"** with the message about contacting the groomer and a **Sign out** button. No redirect loop, no portal chrome. | +| TC-WEB-5.25.6 | 404 fallback Sign-out escape hatch | From TC-WEB-5.25.5 click **Sign out**. | `POST /api/auth/sign-out` fires; browser navigates to `/login`; the Authentik session cookie is cleared. Reloading `/` no longer hits 404 (will show the login page). | +| TC-WEB-5.25.7 | Bridge precedence — impersonation URL wins | 1. Sign in via SSO as a customer. 2. Open a new tab to `https://uat.groombook.dev/?sessionId=`. | The impersonation path runs; the amber banner appears for the impersonated client. The Better Auth bridge is **not** called on this load (`session-from-auth` absent in Network). | +| TC-WEB-5.25.8 | Bridge precedence — dev user wins | In dev mode (e.g. local) with `localStorage["dev-user"]` set to a client persona, navigate to `/`. | The dev-session path runs (`POST /api/portal/dev-session`). The Better Auth bridge is **not** called (`session-from-auth` absent in Network). Staff dev users still redirect to `/admin`. | +| TC-WEB-5.25.9 | Staff Better Auth session does not run the customer bridge | Sign in via SSO with a staff identity. Navigate to `/`. | `App.tsx` routing redirects to `/admin`. `POST /api/portal/session-from-auth` is **not** called. | +| TC-WEB-5.25.10 | Unauthenticated user is sent to login (no infinite loop) | Without signing in, navigate directly to `/`. | `App.tsx` renders the LoginPage. `CustomerPortal` does not render. No `session-from-auth` request is made. | +| TC-WEB-5.25.11 | Session persists across reload via Better Auth cookie | After TC-WEB-5.25.1 succeeds, reload the page. | Portal dashboard re-renders. A fresh `GET /api/auth/get-session` + `POST /api/portal/session-from-auth` pair runs and yields 200/201. Greeting still reads "Hi, <FirstName>". | + ## 6. Pass/Fail Criteria **Pass:** diff --git a/src/__tests__/portal.test.tsx b/src/__tests__/portal.test.tsx index 36f04af..5161aa1 100644 --- a/src/__tests__/portal.test.tsx +++ b/src/__tests__/portal.test.tsx @@ -313,3 +313,164 @@ describe("CustomerPortal session loading", () => { Object.defineProperty(window, "location", { value: originalLocation, writable: true }); }); }); + +// ─── CustomerPortal — Better Auth SSO bridge (GRO-1867) ──────────────────── + +describe("CustomerPortal SSO bridge", () => { + beforeEach(() => { + // Make sure no dev-user leaks across tests + window.localStorage.clear(); + }); + + const brandingResponse = { + ok: true, + json: async () => ({ + businessName: "GroomBook", + primaryColor: "#4f8a6f", + accentColor: "#8b7355", + logoBase64: null, + logoMimeType: null, + }), + } as Response; + + it("bridges Better Auth session via /api/portal/session-from-auth and uses returned sessionId", async () => { + global.fetch = vi.fn((input: RequestInfo, init?: RequestInit) => { + const url = typeof input === "string" ? input : input.toString(); + if (url === "/api/branding") return Promise.resolve(brandingResponse); + if (url === "/api/auth/get-session") { + return Promise.resolve({ + ok: true, + json: async () => ({ user: { email: "customer@example.com", role: "customer" } }), + } as Response); + } + if (url === "/api/portal/session-from-auth" && init?.method === "POST") { + return Promise.resolve({ + ok: true, + status: 201, + json: async () => ({ sessionId: "sso-sess-1", clientId: "client-1", clientName: "Jane Doe" }), + } as Response); + } + // Subsequent portal API calls — surface them so we can assert the header + return Promise.resolve({ ok: true, json: async () => ({}) } as Response); + }) as unknown as typeof fetch; + + const { CustomerPortal } = await import("../portal/CustomerPortal.js"); + render( + + + + ); + + await waitFor(() => { + expect(global.fetch).toHaveBeenCalledWith("/api/auth/get-session", expect.objectContaining({ credentials: "include" })); + }); + await waitFor(() => { + expect(global.fetch).toHaveBeenCalledWith( + "/api/portal/session-from-auth", + expect.objectContaining({ method: "POST", credentials: "include" }) + ); + }); + // Client greeting reflects the bridged customer name (proof the response was consumed) + await waitFor(() => { + expect(screen.getByText(/Hi, Jane/)).toBeInTheDocument(); + }); + // The impersonation banner must NOT appear — this is the customer themselves + expect(screen.queryByRole("button", { name: /End Session/i })).not.toBeInTheDocument(); + }); + + it("shows a friendly fallback when session-from-auth returns 404 (no client record)", async () => { + global.fetch = vi.fn((input: RequestInfo) => { + const url = typeof input === "string" ? input : input.toString(); + if (url === "/api/branding") return Promise.resolve(brandingResponse); + if (url === "/api/auth/get-session") { + return Promise.resolve({ + ok: true, + json: async () => ({ user: { email: "stranger@example.com", role: "customer" } }), + } as Response); + } + if (url === "/api/portal/session-from-auth") { + return Promise.resolve({ + ok: false, + status: 404, + json: async () => ({ error: "No client record found for this user" }), + } as Response); + } + return Promise.resolve({ ok: true, json: async () => ({}) } as Response); + }) as unknown as typeof fetch; + + const { CustomerPortal } = await import("../portal/CustomerPortal.js"); + render( + + + + ); + + await waitFor(() => { + expect(screen.getByText(/Portal access not configured/i)).toBeInTheDocument(); + }); + expect(screen.getByText(/not linked to a customer record/i)).toBeInTheDocument(); + // Sign-out escape hatch is present so the user is not stuck in a loop + expect(screen.getByRole("button", { name: /Sign out/i })).toBeInTheDocument(); + }); + + it("does not call session-from-auth when there is no Better Auth session", async () => { + global.fetch = vi.fn((input: RequestInfo) => { + const url = typeof input === "string" ? input : input.toString(); + if (url === "/api/branding") return Promise.resolve(brandingResponse); + if (url === "/api/auth/get-session") { + return Promise.resolve({ + ok: true, + json: async () => null, + } as Response); + } + return Promise.resolve({ ok: true, json: async () => ({}) } as Response); + }) as unknown as typeof fetch; + + const { CustomerPortal } = await import("../portal/CustomerPortal.js"); + render( + + + + ); + + await waitFor(() => { + expect(global.fetch).toHaveBeenCalledWith("/api/auth/get-session", expect.objectContaining({ credentials: "include" })); + }); + // Wait one tick to ensure no subsequent bridge call is queued + await new Promise((r) => setTimeout(r, 30)); + const bridgeCalls = vi.mocked(global.fetch).mock.calls.filter( + ([u]) => typeof u === "string" && u === "/api/portal/session-from-auth" + ); + expect(bridgeCalls).toHaveLength(0); + }); + + it("skips the bridge for staff Better Auth sessions", async () => { + global.fetch = vi.fn((input: RequestInfo) => { + const url = typeof input === "string" ? input : input.toString(); + if (url === "/api/branding") return Promise.resolve(brandingResponse); + if (url === "/api/auth/get-session") { + return Promise.resolve({ + ok: true, + json: async () => ({ user: { email: "staff@example.com", role: "staff" } }), + } as Response); + } + return Promise.resolve({ ok: true, json: async () => ({}) } as Response); + }) as unknown as typeof fetch; + + const { CustomerPortal } = await import("../portal/CustomerPortal.js"); + render( + + + + ); + + await waitFor(() => { + expect(global.fetch).toHaveBeenCalledWith("/api/auth/get-session", expect.objectContaining({ credentials: "include" })); + }); + await new Promise((r) => setTimeout(r, 30)); + const bridgeCalls = vi.mocked(global.fetch).mock.calls.filter( + ([u]) => typeof u === "string" && u === "/api/portal/session-from-auth" + ); + expect(bridgeCalls).toHaveLength(0); + }); +}); diff --git a/src/portal/CustomerPortal.tsx b/src/portal/CustomerPortal.tsx index a542cc0..db0dcbd 100644 --- a/src/portal/CustomerPortal.tsx +++ b/src/portal/CustomerPortal.tsx @@ -43,6 +43,15 @@ export function CustomerPortal() { // Track whether an impersonation session fetch from URL param is in-flight // Dashboard will not redirect while this is true, allowing the session to load const [isImpersonating, setIsImpersonating] = useState(false); + // Portal session ID for real SSO customers (GRO-1867). Populated by the + // Better Auth → /api/portal/session-from-auth bridge below. Carries the + // X-Impersonation-Session-Id header on subsequent portal API calls without + // triggering the impersonation banner (the customer is themselves). + const [portalSessionId, setPortalSessionId] = useState(null); + // User-facing message when the SSO bridge cannot resolve a client record + // (e.g. authenticated user with no matching client row). Rendered in place + // of the portal chrome instead of bouncing back to /login. + const [authError, setAuthError] = useState(null); const { branding } = useBranding(); const [searchParams, setSearchParams] = useSearchParams(); @@ -98,10 +107,64 @@ export function CustomerPortal() { } }) .finally(() => setInitComplete(true)); - } else { - // No valid session: staff dev users and unauthenticated users fall through here - setInitComplete(true); + return; } + + if (devUser && devUser.type === "staff") { + // Staff dev user — fall through; App.tsx redirects to /admin. + setInitComplete(true); + return; + } + + // Real SSO customer (GRO-1867): bridge a Better Auth session into a portal + // session via POST /api/portal/session-from-auth. The returned session ID + // is used in the X-Impersonation-Session-Id header for portal API calls. + (async () => { + try { + const sessionResp = await fetch("/api/auth/get-session", { credentials: "include" }); + if (!sessionResp.ok) { + setInitComplete(true); + return; + } + let sessionData: { user?: { email?: string; role?: string | null } } | null = null; + try { + sessionData = (await sessionResp.json()) as { user?: { email?: string; role?: string | null } } | null; + } catch { + // Better Auth returns an empty body when there is no session + } + if (!sessionData || !sessionData.user) { + setInitComplete(true); + return; + } + // Staff are routed to /admin by App.tsx; don't run the customer bridge. + if (sessionData.user.role === "staff") { + setInitComplete(true); + return; + } + + const bridgeResp = await fetch("/api/portal/session-from-auth", { + method: "POST", + credentials: "include", + }); + + if (bridgeResp.ok) { + const data = await bridgeResp.json() as { sessionId: string; clientId: string; clientName: string }; + setPortalSessionId(data.sessionId); + setClientName(data.clientName); + } else if (bridgeResp.status === 404) { + // Authenticated but no matching client row — show a friendly message + // instead of bouncing back to /login (which would loop indefinitely). + setAuthError( + "Your account is not linked to a customer record. Please contact your groomer to set up portal access." + ); + } + // 401/other: fall through; App.tsx render guard will redirect to /login. + } catch { + // Network error — fall through; the render guard will redirect to /login. + } finally { + setInitComplete(true); + } + })(); }, []); const handleEnd = useCallback(async () => { @@ -157,7 +220,7 @@ export function CustomerPortal() { const isReadOnly = session?.status === "active"; const renderSection = () => { - const sessionId = session?.id ?? null; + const sessionId = session?.id ?? portalSessionId; switch (activeSection) { case "dashboard": return ; @@ -183,7 +246,40 @@ export function CustomerPortal() { // For client dev users, we stay on the portal even if session is null — the dev-session // response may not have id set immediately, or there may be timing issues with the // session state. Dev users are verified via localStorage and the dev-session flow. - if (initComplete && !session) { + // SSO customers are recognised by portalSessionId (set by the Better Auth bridge). + if (initComplete && !session && !portalSessionId) { + if (authError) { + // GRO-1867: graceful 404 fallback — authenticated user has no client row. + return ( +
+
+
+ +
+

Portal access not configured

+

{authError}

+ +
+
+ ); + } const devUser = getDevUser(); if (devUser && devUser.type === "staff") { return ; -- 2.52.0 From 3297903d5cdf4e3640932feaf100ba761dd21a3d Mon Sep 17 00:00:00 2001 From: Flea Flicker Date: Mon, 1 Jun 2026 16:02:46 +0000 Subject: [PATCH 2/2] fix(GRO-2011): always fetch /api/setup/status, even for unauth users MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The second useEffect in App skipped the setup/status fetch when `!authDisabled && !session` was true. In the deployed bundle the `needsSetup` state therefore stayed `null` for unauth users, and a later render short-circuit rendered nothing — producing the blank white viewport at https://uat.groombook.dev/login. Drop the unauth skip clause so `/api/setup/status` is always fetched as soon as the auth state is known. The unauth branch in the render is handled before `needsSetup` is consulted, so this is safe and removes the stuck-`null` state. Adds: - New unit test in src/__tests__/App.test.tsx asserting the unauthenticated path calls /api/setup/status. - UAT playbook entry TC-WEB-5.1.5 covering the blank-viewport regression scenario. Co-Authored-By: Paperclip --- UAT_PLAYBOOK.md | 1 + src/App.tsx | 11 +++++-- src/__tests__/App.test.tsx | 59 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 68 insertions(+), 3 deletions(-) diff --git a/UAT_PLAYBOOK.md b/UAT_PLAYBOOK.md index e6dbc30..271b295 100644 --- a/UAT_PLAYBOOK.md +++ b/UAT_PLAYBOOK.md @@ -53,6 +53,7 @@ export const { signIn, signOut, useSession, changePassword } = authClient; | TC-WEB-5.1.2 | OIDC redirect | Click OIDC login button | Redirected to OIDC provider, then back to app with session established | | TC-WEB-5.1.3 | Logout | Click logout button | Session cleared, redirected to login page | | TC-WEB-5.1.4 | Session indicator | After successful login | User info/initials visible in UI indicating active session | +| TC-WEB-5.1.5 | Unauthenticated `/login` renders the form (GRO-2011) | In a private/incognito window with no session cookie, navigate to UAT `/login` | React root mounts; the GroomBook sign-in card with the OIDC button is visible. Network tab shows `/api/auth/get-session` 200, `/api/setup/status` 200, and the login form is rendered (NOT a blank white viewport). | ### 5.2 Authentication — VITE_API_URL Set diff --git a/src/App.tsx b/src/App.tsx index 30d2091..1bbb17f 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -327,11 +327,16 @@ export function App() { .catch(() => setAuthDisabled(false)); }, []); - // After session is confirmed, check if setup is needed + // After session is confirmed, check if setup is needed. + // Always run the setup/status fetch as soon as the auth state is known — even for + // unauthenticated users, so the `needsSetup` value is in place if they sign in + // mid-session. The unauth branch in the render below is handled before + // `needsSetup` is consulted, so this is safe and avoids a stuck-`null` state. + // See GRO-2011. useEffect(() => { if (authDisabled === null || sessionLoading) return; - // Skip if no authenticated session (will redirect to login or dev selector) - if (!authDisabled && !session) return; + // In dev mode, only fetch when a dev user has been selected — otherwise the + // user is mid-redirect to the dev login selector and we don't need setup state. if (authDisabled && !getDevUser()) return; fetch("/api/setup/status") diff --git a/src/__tests__/App.test.tsx b/src/__tests__/App.test.tsx index ea5aea8..edddc4f 100644 --- a/src/__tests__/App.test.tsx +++ b/src/__tests__/App.test.tsx @@ -121,6 +121,65 @@ describe("App navigation", () => { }); }); +describe("GRO-2011 — setup/status fetch for unauthenticated users", () => { + it("calls /api/setup/status for unauthenticated users so needsSetup is never stuck null", async () => { + const setupStatusCalls: string[] = []; + + global.fetch = vi.fn((url: string) => { + if (url === "/api/dev/config") { + return Promise.resolve({ + ok: true, + json: async () => ({ authDisabled: false }), + } as Response); + } + if (url === "/api/auth/get-session") { + // Better Auth returns 200 with null session for unauthenticated users. + return Promise.resolve({ + ok: true, + json: async () => null, + } as unknown as Response); + } + if (url === "/api/setup/status") { + setupStatusCalls.push(url); + return Promise.resolve({ + ok: true, + json: async () => ({ needsSetup: false }), + } as Response); + } + if (url === "/api/branding") { + return Promise.resolve({ + ok: true, + json: async () => ({ + businessName: "GroomBook", + primaryColor: "#4f8a6f", + accentColor: "#8b7355", + logoBase64: null, + logoMimeType: null, + }), + } as Response); + } + return Promise.resolve({ ok: true, json: async () => [] } as Response); + }) as unknown as typeof fetch; + + render( + + + + ); + + // The login page should be rendered for the unauthenticated user. + await screen.findByText("Sign in to continue"); + + // Crucially, /api/setup/status must be called even when the user is unauthenticated — + // otherwise `needsSetup` stays null and a later code path can short-circuit to a + // blank page (GRO-2011). + await waitFor(() => { + expect(setupStatusCalls.length).toBeGreaterThanOrEqual(1); + }); + expect(setupStatusCalls[0]).toBe("/api/setup/status"); + }); +}); + describe("Dev login selector", () => { it("redirects to /login when auth is disabled and no user selected", async () => { global.fetch = vi.fn((url: string) => { -- 2.52.0