diff --git a/AUTH_SYSTEM.md b/AUTH_SYSTEM.md new file mode 100644 index 00000000000..6d4b4b37313 --- /dev/null +++ b/AUTH_SYSTEM.md @@ -0,0 +1,259 @@ +# Authentication System Documentation + +This authentication system provides a complete solution for handling Supabase authentication tokens via cookies and query strings. + +## Features + +- **Token-based Authentication**: Accepts authentication tokens via query strings or POST requests +- **Automatic Cookie Management**: Stores tokens securely as HTTP-only cookies +- **Token Refresh**: Automatically refreshes expired tokens using refresh tokens +- **Route Protection**: Middleware to protect routes requiring authentication +- **Client-side Hooks**: React hooks for managing authentication state +- **Session Management**: Proper login/logout functionality + +## API Endpoints + +### Authentication Callback +Handle authentication tokens from external services or redirects. + +#### GET `/api/auth/callback` +``` +GET /api/auth/callback?token=ACCESS_TOKEN&refresh_token=REFRESH_TOKEN&redirect_to=/dashboard +``` + +Parameters: +- `token` or `access_token` (required): The Supabase access token +- `refresh_token` (optional): The refresh token for automatic token renewal +- `redirect_to` (optional): URL to redirect to after successful authentication (default: "/") + +#### POST `/api/auth/callback` +```json +POST /api/auth/callback +Content-Type: application/json + +{ + "access_token": "ACCESS_TOKEN", + "refresh_token": "REFRESH_TOKEN", + "redirect_to": "/dashboard" +} +``` + +### Authentication Check +Verify current authentication status. + +#### GET `/api/auth/check` +``` +GET /api/auth/check +``` + +Returns: +```json +{ + "authenticated": true, + "user": { + "id": "user_id", + "email": "user@example.com", + "user_metadata": {} + }, + "userInfo": { + "id": "user_id", + "email": "user@example.com", + "user_metadata": {} + } +} +``` + +### Token Refresh +Manually refresh an expired access token. + +#### POST `/api/auth/refresh` +``` +POST /api/auth/refresh +``` + +Uses the refresh token stored in cookies to get a new access token. + +### Logout +Clear authentication cookies and end the session. + +#### POST `/api/auth/logout` +```json +POST /api/auth/logout +``` + +#### GET `/api/auth/logout` +``` +GET /api/auth/logout?redirect_to=/login +``` + +### User Information +Get detailed user information (protected route). + +#### GET `/api/user` +``` +GET /api/user +``` + +Returns detailed user information including metadata. + +## Client-side Usage + +### Using the useAuth Hook + +```tsx +import { useAuth } from "../hooks/useAuth"; + +function MyComponent() { + const { user, authenticated, loading, login, logout, checkAuth } = useAuth(); + + if (loading) { + return
Welcome, {user?.email}!
+ +User ID: {user.id}
+Loading authentication status...
+
+ GET
+ /api/auth/callback?token=YOUR_SUPABASE_TOKEN&refresh_token=REFRESH_TOKEN&redirect_to=/profile
+
+
+ POST /api/auth/callback
+
+ {`{"access_token": "token", "refresh_token": "refresh"}`}
+
+ + Visit the{" "} + + login page + {" "} + to enter your Supabase tokens manually. +
+GET /api/auth/check - Check auth status
+ POST /api/auth/callback - Login with tokens
+ POST /api/auth/refresh - Refresh access token
+ POST /api/auth/logout - Logout and clear
+ cookies
+ GET /api/user - Get user information
+ GET /profile - User profile page
+ GET /chat - Chat interface (if implemented)
+ GET /settings - Settings page (if implemented)
+
+ 📚 See AUTH_SYSTEM.md for detailed documentation
+
+ Enter your Supabase authentication token +
+
+ You can also authenticate by visiting:{" "}
+
+ /api/auth/callback?token=YOUR_TOKEN
+
+
{user?.id}
+{user.email}
+
+ {JSON.stringify(user.user_metadata, null, 2)}
+
+