Authentication & Identity
Relevant source files
The following files were used as context for generating this wiki page:
Authentication and Identity in ThinkEx are managed through the Better Auth framework, utilizing a PostgreSQL database with the Drizzle ORM adapter. The system supports both authenticated users (via Google OAuth) and anonymous users, allowing for a seamless transition where data from anonymous sessions can be migrated to permanent accounts. Identity management is deeply integrated into the workspace security model, ensuring that access to resources is restricted based on ownership or explicit collaborator permissions.
Sources: src/lib/auth.ts:1-10, README.md:58, src/lib/api/workspace-helpers.ts:15-30
Core Architecture
The authentication system is built on a "minimal" configuration of Better Auth, optimized for Next.js environments. It leverages specialized plugins for anonymous user support and cookie management.
Identity Providers and Configuration
ThinkEx primarily uses Google OAuth for social authentication. The configuration specifies a redirectURI targeting the /api/auth/callback/google endpoint and requests offline access to facilitate session management.
Sources: src/lib/auth.ts:40-48
| Option | Type | Default / Value | Description |
|---|---|---|---|
database | DrizzleAdapter | PostgreSQL | Uses Drizzle ORM to interface with the database. |
socialProviders | Object | Configured with clientId and clientSecret. | |
session.expiresIn | Number | 2,592,000 (30 days) | Duration before a session token expires. |
session.updateAge | Number | 1,296,000 (15 days) | Interval at which session expiration is refreshed. |
advanced.useSecureCookies | Boolean | process.env.NODE_ENV === "production" | Ensures cookies are HTTPS only in production. |
Sources: src/lib/auth.ts:25-27, src/lib/auth.ts:65-80, src/lib/auth.ts:93-95
Session Security
Sessions are secured using httpOnly and secure cookies to prevent Cross-Site Scripting (XSS) access. The system also implements IP address tracking via headers like x-forwarded-for and cf-connecting-ip for session binding.
Sources: src/lib/auth.ts:96-115
Authentication Flow
The authentication flow handles both standard sign-in and invitation-based onboarding.
Sign-in and Invitations
The /auth/[path] route serves as the entry point for both sign-in and sign-up. If a user arrives via an invite token, the system fetches workspace and inviter details from the workspaceInvites and user tables to personalize the onboarding experience.
Sources: src/app/auth/[path]/page.tsx:32-65
Anonymous User Migration
ThinkEx allows users to interact with the platform anonymously. When an anonymous user later signs up or links an account, a migration process is triggered via the anonymous plugin.
Conflict Resolution Logic
- Slug Conflicts: The system checks if the anonymous user's workspace slugs conflict with existing slugs in the target account. If a conflict is found, it appends a counter (e.g.,
-1,-2) to the slug. - Workspace Migration: Updates the
userIdin theworkspacestable from the anonymous ID to the new permanent ID. - Event Migration: Migrates historical data in the
workspaceEventstable to ensure the user's activity history remains intact.
Sources: src/lib/auth.ts:121-175
Server-Side Authorization
Authorization is enforced at the API level through helper functions that verify sessions and workspace permissions.
Permission Levels
The system distinguishes between three primary permission levels:
- Owner: Full access to the workspace.
- Editor: Ability to modify content within the workspace.
- Viewer: Read-only access.
Sources: src/lib/api/workspace-helpers.ts:55-65
Verification Helpers
| Function | Description | Source File |
|---|---|---|
getAuthenticatedUser() | Retrieves userId, name, and email from the current session headers. | workspace-helpers.ts:15-30 |
requireAuth() | Enforces authentication; throws a 401 Unauthorized if no session exists. | workspace-helpers.ts:155-162 |
verifyWorkspaceAccess() | Checks if a user is the owner or a collaborator with specific permission levels. | workspace-helpers.ts:54-95 |
Sources: src/lib/api/workspace-helpers.ts
Integration in API Routes
API routes like /api/chat and /api/workspaces/autogen utilize these helpers to ensure that AI interactions and workspace generations are performed on behalf of a valid user.
Database Schema Integration
The authentication system interacts with several tables to maintain identity and state.
| Table | Purpose in Authentication |
|---|---|
user | Stores core identity (managed by Better Auth). |
userProfiles | Created automatically after user creation via databaseHooks. |
workspaces | Linked to users via userId; cleaned up on user deletion. |
workspaceCollaborators | Maps users to workspaces with specific permission levels. |
workspaceEvents | Tracks user activity, migrated during anonymous account linking. |
Sources: src/lib/auth.ts:30-38, src/lib/auth.ts:85-92, src/lib/api/workspace-helpers.ts:77-85
Implementation Summary
Authentication and Identity in ThinkEx provide a robust foundation for secure, multi-user collaboration while maintaining a low barrier to entry via anonymous access. By utilizing Better Auth and custom Drizzle-based hooks, the project ensures that user data is correctly associated with permanent accounts and that workspace resources are strictly protected through verified ownership and collaboration checks.