integreat/docs/testing/behaviors/auth.md

Authentication Behaviors

Overview

Authentication in Integreat uses Google OAuth 2.0 as the primary identity provider. Users authenticate via Google, receive a JWT token, and establish a server-side session. The system supports role-based access control (admin, user, read-only), client-scoped permissions, session versioning for SSR rollout, and admin impersonation via signed JWT tokens.

Testing Philosophy

• Prefer unit tests for pure business logic (JWT generation, compression, validation)
• Use integration tests for database interactions and cross-system flows (OAuth callback, session management)
• Use UI tests only for end-to-end happy paths that touch multiple pages
• Every behavior must be user-visible; no tests for implementation details

---

Testing Patterns

Pattern: OAuth Login Flow

The standard authentication flow follows these steps:

1. Unauthenticated user navigates to a protected page
2. User is redirected to /login
3. User clicks "Sign in with Google"
4. Browser redirects to Google OAuth consent screen
5. User consents and Google redirects to /api/oauth?code=<code>&state=<state>
6. Server exchanges code for token, fetches profile, finds/creates user
7. Server redirects to original page (or /) with ?jwt=<token>
8. Client reads JWT and establishes session

Test implications: Integration test the OAuth callback handler. UI test only the happy path once.

Pattern: Middleware Stack

Every protected route passes through authentication middleware:

1. wrap-session-version — validates session version, redirects to login if outdated
2. wrap-secure — checks for authenticated session, redirects to login if missing
3. wrap-admin — checks for admin role, redirects to login if not admin
4. wrap-client-redirect-unauthenticated — converts 401 responses to HTMX redirects

Test implications: Integration test each middleware independently. UI tests only verify redirect behavior.

Pattern: JWT Claims

The JWT token contains user identity and permissions:

1. :user, :exp, :db/id, :user/role, :user/name for all users
2. :gz-clients (compressed) for admin and read-only users
3. :user/clients (plain) for regular users

Test implications: Unit test JWT generation for each role type.

---

Login

Display Behaviors

#	Behavior	Test Strategy	Status
1.1	It should display a "Sign in with Google" button on the login page	UI	[ ]

OAuth Behaviors

#	Behavior	Test Strategy	Status
1.2	It should redirect to Google OAuth when the user clicks "Sign in with Google"	UI	[ ]
1.3	It should exchange the authorization code for an access token on callback	Integration	[ ]
1.4	It should fetch the user's Google profile using the access token	Integration	[ ]
1.5	It should create a new user account when the user logs in for the first time	Integration	[ ]
1.6	It should find the existing user account on subsequent logins	Integration	[ ]
1.7	It should redirect to the original page after successful OAuth	Integration	[ ]
1.8	It should redirect to the root page when no return URL is provided	Integration	[ ]
1.9	It should establish a server-side session with user identity and version	Integration	[ ]
1.10	It should pass the JWT token in the query string after successful OAuth	Integration	[ ]
1.11	It should display the user's clients and data after successful login	UI	[ ]
1.12	It should handle users without email via Google provider ID	Integration	[ ]
1.13	It should return 401 with error message when the OAuth code is missing	Integration	[ ]
1.14	It should return 401 when the OAuth code is invalid or expired	Integration	[ ]
1.15	It should return 401 and log a warning when the Google network request fails	Integration	[ ]

---

Logout

#	Behavior	Test Strategy	Status
2.1	It should clear the session when the user navigates to /logout	Integration	[ ]
2.2	It should redirect to the login page after logout	Integration	[ ]
2.3	It should remain idempotent when logging out without an active session	Integration	[ ]

---

Impersonation

#	Behavior	Test Strategy	Status
3.1	It should allow admin users to assume another user's identity via signed JWT	Integration	[ ]
3.2	It should validate the impersonation JWT signature with :jwt-secret and :hs512	Integration	[ ]
3.3	It should reject expired impersonation JWTs	Integration	[ ]
3.4	It should block non-admin users from accessing /impersonate	Integration	[ ]
3.5	It should block unauthenticated users from accessing /impersonate	Integration	[ ]
3.6	It should replace the admin's session with the impersonated user's session	Integration	[ ]

---

Session Management

Authentication Gate Behaviors

#	Behavior	Test Strategy	Status
4.1	It should allow authenticated requests to proceed to protected routes	Integration	[ ]
4.2	It should redirect unauthenticated users to /login with a redirect-to parameter	Integration	[ ]
4.3	It should return hx-redirect: /login for unauthenticated HTMX requests	Integration	[ ]

Admin Gate Behaviors

#	Behavior	Test Strategy	Status
5.1	It should allow admin requests to proceed to admin-only routes	Integration	[ ]
5.2	It should redirect non-admin users to /login when accessing admin routes	Integration	[ ]

Session Version Behaviors

#	Behavior	Test Strategy	Status
6.1	It should invalidate sessions with outdated version numbers	Integration	[ ]
6.2	It should redirect to /login when an outdated session accesses normal routes	Integration	[ ]
6.3	It should return hx-redirect: /login for outdated sessions on HTMX routes	Integration	[ ]
6.4	It should return 401 for outdated sessions on GraphQL routes	Integration	[ ]
6.5	It should treat sessions without a version as outdated	Integration	[ ]

---

Cross-Cutting Behaviors

JWT Behaviors

#	Behavior	Test Strategy	Status
7.1	It should generate a JWT containing the user's role and client access on login	Unit	[ ]
7.2	It should compress the client list for admin users to fit in the JWT	Unit	[ ]
7.3	It should compress the client list for read-only users to fit in the JWT	Unit	[ ]
7.4	It should include a plain client list for regular users in the JWT	Unit	[ ]
7.5	It should create API tokens with admin role and 1000-day expiration	Unit	[ ]

Middleware Behaviors

#	Behavior	Test Strategy	Status
8.1	It should convert 401 responses to HTMX redirects for unauthenticated users	Integration	[ ]

Role-Based Behaviors

#	Behavior	Test Strategy	Status
9.1	It should allow admin users to access all clients	Integration	[ ]
9.2	It should allow regular users to access only their assigned clients	Integration	[ ]
9.3	It should allow read-only users to access all clients with view-only permissions	Integration	[ ]
9.4	It should handle admin users with no clients by providing an empty compressed list	Unit	[ ]
9.5	It should handle regular users with no clients by providing an empty client vector	Unit	[ ]

Security Behaviors

#	Behavior	Test Strategy	Status
10.1	It should reject tampered JWTs during impersonation	Integration	[ ]
10.2	It should treat sessions with nil identity as unauthenticated	Integration	[ ]

---

Test Data Requirements

Entity	Requirements
Users	Admin user with multiple clients; regular user with subset of clients; read-only user with multiple clients; new user (not in database) with Google provider details; existing user with Google provider details
Clients	Multiple clients with :client/code, :client/name, :client/locations; client associations on users
OAuth Mock	Mock Google token endpoint responses (success and failure); mock Google userinfo endpoint responses

Existing Tests to Preserve

• None identified

Dependencies

• Google OAuth 2.0 (authorization code exchange and userinfo retrieval)
• Buddy JWT (token signing/unsigning with HS512)
• Datomic (user lookup and creation)
• Legacy SPA (login and needs-activation pages, no SSR tests)