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:

  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].