Session Management

gau’s flexibility is achieved by supporting two primary session management strategies: cookie-based and token-based sessions.

Cookie-Based Sessions (Web Apps)

This is the most common method for full-stack web apps.

How It Works

1. Sign-In: The user is redirected to the OAuth provider.
2. Callback: After successful authentication, the provider redirects the user back to your apps’s callback URL (e.g., /api/auth/github/callback).
3. Session Cookie: gau validates the callback, creates a user session, and stores the session information in a secure, HttpOnly cookie.
4. Authenticated Requests: The browser automatically includes this cookie with every subsequent request to your backend. The server can then validate the cookie to identify the user.

This flow is handled automatically by the framework helpers, like @rttnd/gau/sveltekit.

The session cookie is named __gau-session-token by default and its attributes can be configured via the cookies option in createAuth.

---

Token-Based Sessions (Native Apps & SPAs)

For environments where cookies are not ideal or feasible - like desktop apps, mobile apps, or SPAs that are decoupled from their backend - gau uses a token-based flow.

How It Works

This flow relies on a URL hash to transfer the session token from the OAuth provider back to the app. For Tauri, it uses deep linking (custom URL schemes).

1. Sign-In: The client-side signIn function (e.g., from @rttnd/gau/client/svelte) opens the system’s web browser to the OAuth provider’s authorization URL. A redirectTo parameter is included, pointing to a custom URL scheme (e.g., my-app://oauth/callback).
2. Callback & Redirect: After the user approves, the provider redirects to a special page hosted by your backend. This page receives the token, then immediately performs an HTML redirect to the custom URL scheme, embedding the session token in the URL’s hash (e.g., my-app://oauth/callback#token=...).
3. Deep Link Handling: The operating system captures this custom URL and re-opens your native app. The app’s deep link handler receives the URL, extracts the session token.
4. Token Storage: The client library then stores the token in two places:
   • localStorage: For the client to attach it to subsequent API requests in the Authorization: Bearer <token> header.
   • A non-HttpOnly cookie: This allows server-side rendering logic (e.g., in a SvelteKit handle hook) to access the session on the initial page load, preventing a “logged-out” flash.
5. Authenticated Requests: The client is now responsible for including this token in the Authorization header for all subsequent API requests.

This is entirely managed by gau. The client libraries automatically handle storing the token and including it in requests, while the backend is designed to render the necessary redirect page.

See the Tauri integration guide for a practical example.

Session Strategy

You can control this behavior using the session.strategy option in createAuth.

• 'auto' (Default): gau automatically switches between cookie-based and token-based sessions. It uses cookies by default but will switch to the token flow if it detects a redirect to a different host or a custom URL scheme.
• 'cookie': Forces cookie-based sessions, even for cross-origin redirects (as long as the host is trusted).
• 'token': Forces token-based sessions, even for same-origin redirects.