aboutsummaryrefslogtreecommitdiffstats
path: root/docs/SESSION_GUIDE.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/SESSION_GUIDE.md')
-rw-r--r--docs/SESSION_GUIDE.md221
1 files changed, 0 insertions, 221 deletions
diff --git a/docs/SESSION_GUIDE.md b/docs/SESSION_GUIDE.md
deleted file mode 100644
index 1f9a228..0000000
--- a/docs/SESSION_GUIDE.md
+++ /dev/null
@@ -1,221 +0,0 @@
-# Session Management Guide
-
-This guide explains how to use the session-based authentication system implemented in the backend.
-
-## Overview
-
-The backend now supports persistent login sessions using:
-- **express-session** for server-side session management
-- **HTTP-only cookies** for secure session storage
-- **Database session tracking** with automatic cleanup
-- **CSRF protection** through HTTP-only cookies
-
-## Environment Setup
-
-1. Copy `.env.example` to `.env`:
-```bash
-cp .env.example .env
-```
-
-2. Update the `SESSION_SECRET` in your `.env` file with a secure random string:
-```
-SESSION_SECRET="your-very-secure-secret-key-change-this-in-production-make-it-long-and-random"
-```
-
-## API Endpoints
-
-### Authentication Endpoints
-
-#### Register User
-- **POST** `/api/register`
-- **Body**: `{ username, password, name, email }`
-- **Response**: User data + session created
-- **Sets**: HTTP-only session cookie
-
-#### Login
-- **POST** `/api/authenticate`
-- **Body**: `{ username, password }`
-- **Response**: User data + session created
-- **Sets**: HTTP-only session cookie
-
-#### Logout
-- **POST** `/api/logout`
-- **Requires**: Valid session
-- **Response**: Success message
-- **Clears**: Session cookie and database sessions
-
-### Session Management
-
-#### Check Session Status
-- **GET** `/api/session`
-- **Response**: `{ authenticated: boolean, user?: UserData }`
-- **Use**: Check if user is still logged in
-
-#### Get Current User
-- **GET** `/api/me`
-- **Requires**: Valid session
-- **Response**: Current user data
-
-## Frontend Integration
-
-### Making Authenticated Requests
-
-Always include credentials in your fetch requests:
-
-```javascript
-// Example fetch with credentials
-const response = await fetch('http://localhost:5000/api/me', {
- method: 'GET',
- credentials: 'include', // This is crucial!
- headers: {
- 'Content-Type': 'application/json',
- }
-});
-```
-
-### Login Flow Example
-
-```javascript
-// Login
-const loginResponse = await fetch('http://localhost:5000/api/authenticate', {
- method: 'POST',
- credentials: 'include',
- headers: {
- 'Content-Type': 'application/json',
- },
- body: JSON.stringify({
- username: 'user@example.com',
- password: 'password123'
- })
-});
-
-if (loginResponse.ok) {
- const userData = await loginResponse.json();
- console.log('Logged in:', userData);
- // Session cookie is automatically set
-}
-```
-
-### Check Authentication Status
-
-```javascript
-// Check if user is still logged in
-const sessionResponse = await fetch('http://localhost:5000/api/session', {
- method: 'GET',
- credentials: 'include'
-});
-
-const sessionData = await sessionResponse.json();
-if (sessionData.authenticated) {
- console.log('User is logged in:', sessionData.user);
-} else {
- console.log('User is not logged in');
-}
-```
-
-### Logout
-
-```javascript
-// Logout
-const logoutResponse = await fetch('http://localhost:5000/api/logout', {
- method: 'POST',
- credentials: 'include'
-});
-
-if (logoutResponse.ok) {
- console.log('Logged out successfully');
- // Session cookie is automatically cleared
-}
-```
-
-## Security Features
-
-### Session Security
-- **HTTP-only cookies**: Prevents XSS attacks
-- **Secure cookies**: Enabled in production (HTTPS)
-- **SameSite protection**: Prevents CSRF attacks
-- **Session expiration**: 24-hour automatic expiry
-
-### Database Sessions
-- Sessions are stored in the database for server-side validation
-- Expired sessions are automatically cleaned up every hour
-- User logout removes all sessions for that user
-
-### Password Security
-- Passwords are hashed with bcrypt (12 rounds)
-- Unique salt per user for additional security
-- Original password never stored
-
-## Middleware
-
-### `requireAuth` Middleware
-Protects routes that need authentication:
-
-```javascript
-app.get('/api/protected-route', requireAuth, (req, res) => {
- // req.user contains the authenticated user data
- const user = req.user;
- res.json({ message: 'This is protected', user });
-});
-```
-
-## Production Considerations
-
-### Environment Variables
-```env
-SESSION_SECRET="your-production-secret-minimum-32-characters-long"
-NODE_ENV="production"
-FRONTEND_URL="https://yourdomain.com"
-```
-
-### Security Settings
-In production, ensure:
-1. `SESSION_SECRET` is a strong, unique string
-2. `secure: true` in cookie settings (HTTPS only)
-3. Proper CORS origin configuration
-4. HTTPS enabled for your domain
-
-### Database
-- Consider using PostgreSQL or MySQL instead of SQLite
-- Implement database connection pooling
-- Set up database backups
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Session not persisting**: Make sure `credentials: 'include'` is set in frontend requests
-2. **CORS errors**: Verify CORS origin matches your frontend URL
-3. **Session expires immediately**: Check system time and session expiration settings
-4. **Authentication fails after server restart**: Sessions are stored in database, so they should persist
-
-### Debug Session Issues
-
-Check session status:
-```javascript
-fetch('http://localhost:5000/api/session', {
- credentials: 'include'
-}).then(r => r.json()).then(console.log);
-```
-
-### Clear All Sessions
-If you need to force logout all users:
-```sql
-DELETE FROM Session;
-```
-
-## Database Schema
-
-The session system adds a `Session` table:
-
-```prisma
-model Session {
- id String @id @default(cuid())
- userId Int
- user User @relation(fields: [userId], references: [id], onDelete: Cascade)
- createdAt DateTime @default(now())
- expiresAt DateTime
-}
-```
-
-Sessions are automatically linked to users and cleaned up when users are deleted. \ No newline at end of file
send patches to the email below
yukais@pinapelz.com
include the subject [PATCH repo_name]
pinapelz.com
homepage