Sketches

Rough, non-binding structures.

UserPresentation {
  nameColor?: string
  badges?: Badge[]
  flair?: Flair
}

This is not a proposal.

Authentication process:

We want to use the chat backend for as much authentication as possible. To handle this the primary flow from a next-js fronr end is so:

• trigger social signon from the front end sdk, with a local proxied api endpoint as the callback.
• this will allow for all oauth to go through the backend, while exposing the /api/auth/get-session end point for auth in the front end.
• idealy - this callback should handle the authentication painlesly and re-redirect the user on sucess.

Below is a clean MDX-ready write-up you can drop directly into your docs. Tone is intentionally implementation-focused and backend-centric.

title: Authentication Flow (Backend-First OAuth) description: Centralised OAuth and session handling via the Chat Backend

Overview

Authentication is owned by the Chat Backend. The Next.js frontend delegates all OAuth handling to the backend and only consumes a verified session via a single API endpoint.

This achieves:

• Centralised OAuth configuration
• Shared auth across chat, embeds, and future clients
• Minimal auth logic in the frontend
• Cookie-based session continuity across subdomains

Design Goals

• Backend-first authentication OAuth providers (Google, Twitch, etc.) are configured and handled exclusively by the Chat Backend.

• Frontend as a thin client The frontend never handles OAuth tokens directly.

• Single source of truth for sessions /api/auth/get-session is the only frontend-facing auth endpoint.

• Seamless redirect UX OAuth callbacks complete silently and redirect the user back to the originating frontend route.

High-Level Flow

1. User clicks Sign in in the Next.js frontend
2. Frontend invokes the social sign-in SDK
3. OAuth callback is routed to a proxied backend endpoint
4. Backend:
   • Validates provider response
   • Creates or fetches user
   • Issues a session cookie
5. Backend redirects the user back to the frontend
6. Frontend calls /api/auth/get-session to hydrate auth state

Mermaid Sequence Diagram

Frontend Responsibilities

The frontend does not:

• Store OAuth tokens
• Handle provider secrets
• Persist sessions manually

It only:

• Initiates sign-in via the SDK
• Calls /api/auth/get-session
• Hydrates user state into React context / store

Example usage:

const res = await fetch(
  `${process.env.NEXT_PUBLIC_API_URL}/api/auth/get-session`,
  { credentials: "include" }
);
 
const data = await res.json();

Backend Responsibilities

The Chat Backend is responsible for:

• OAuth provider configuration
• Callback handling
• User persistence
• Session issuance
• Cookie management
• Cross-app authentication consistency

The OAuth callback endpoint should:

• Handle errors gracefully
• Avoid user-visible intermediate states
• Redirect immediately on success or failure

Redirect Strategy

• OAuth callbacks terminate in the backend

• Backend performs final redirect to:

  • The original page
  • Or a default route (e.g. /dashboard)

• Frontend never parses OAuth parameters

This avoids:

• Token leakage
• Frontend-only race conditions
• Duplicate auth logic

Benefits

• One auth system for:

  • Chat
  • Embeds
  • Admin
  • Future services

• Reduced frontend complexity

• Easier provider rotation and extension

• Clear trust boundary

Summary

This authentication model treats the Chat Backend as the identity authority and the frontend as a consumer of verified session state.

It scales cleanly as more clients, embeds, and services are added—without duplicating OAuth logic or leaking credentials.