Better Auth Integration Skill

This skill provides the source of truth for integrating Better Auth into a polyglot stack (Go backend + React frontend). It ensures secure session management, type-safe API calls, and seamless TanStack Query integration.

Architectural Standards

1. Unified Auth Schema & Plugins

• •Database: Use the Better Auth standard schema. Standardize table names to user, session, account, verification.
• •Plugins: Enable and configure:
  • •organization: For multi-tenant isolation.
  • •sso: For SAML/OIDC enterprise login.
  • •two-factor: For TOTP/Email/SMS MFA.
  • •admin: For user impersonation and management.

2. Go Backend Integration (The Bridge)

• •Middleware: Implement a robust middleware that:
  1. •Extracts the better-auth.session_token cookie.
  2. •Validates it against the session table.
  3. •Handles Token Refresh by checking the expiresAt and performing a silent refresh via the Better Auth API if needed.
• •Context: Store the full User and Organization objects in the request context for downstream RBAC.

3. TanStack Query Frontend (The Consumer)

• •Session Lifecycle:
  typescript

  export const useAuth = () => {
    return useQuery({
      queryKey: ['auth', 'session'],
      queryFn: async () => {
        const res = await authClient.getSession();
        if (res.error) throw res.error;
        return res.data;
      },
      staleTime: 1000 * 60 * 5, // 5 minutes
      refetchOnWindowFocus: true,
    });
  };
  

• •Interceptors: Implement an Axios interceptor that catches 401s and attempts an authClient.refreshToken() before failing and redirecting to login.

4. Security & Isolation

• •CORS: Strictly allow only your frontend origin. Enable credentials: true.
• •CSRF: Better Auth handles CSRF via a custom header or double-submit cookie. Ensure your Go backend validates these if performing non-GET requests.
• •Tenant Mapping: Every query MUST be filtered by organizationId. Never rely on frontend-provided IDs; always derive from the validated session.

Interaction Protocol

• •Input: Database schema, Go server setup, or React frontend requirements.
• •Output: Detailed plugin configuration, Go middleware implementations, and TanStack Query hooks.

Tag: Start your response with [BETTER-AUTH].

Implementation Workflow

1. •Schema Sync: Define the Better Auth schema in the Go database.
2. •API Bridge: Implement the session verification middleware in Go.
3. •Frontend Setup: Initialize the Better Auth client in the Vite app.
4. •Query Integration: Wrap auth state in TanStack Query for global reactivity.

Tag: Start your response with [BETTER-AUTH].