gufi-cli 0.1.50 → 0.1.52

package/docs/dev-guide/1-05-authentication.md

@@ -0,0 +1,427 @@
+---
+id: authentication
+title: "Authentication & Security"
+description: "JWT tokens, sessions, and security best practices"
+icon: Key
+category: dev
+part: 1
+---
+
+# Authentication & Security
+
+JWT tokens, sessions, and security best practices
+
+## Authentication Flow
+
+Gufi uses a dual-layer JWT authentication system for security and seamless user experience.
+
+### Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Authentication Flow                       │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Login Request                                              │
+│       │                                                     │
+│       ▼                                                     │
+│  ┌─────────────┐                                           │
+│  │   Backend   │──────┐                                    │
+│  │  Validates  │      │                                    │
+│  └─────────────┘      │                                    │
+│       │               │                                     │
+│       ▼               ▼                                     │
+│  ┌─────────────┐  ┌─────────────┐                          │
+│  │   Access    │  │   Refresh   │                          │
+│  │   Token     │  │   Cookie    │                          │
+│  │  (15 min)   │  │  (7 days)   │                          │
+│  └─────────────┘  └─────────────┘                          │
+│       │                   │                                 │
+│       ▼                   │                                 │
+│  API Requests ◄───────────┘ (auto-refresh)                 │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Login Process
+
+### Step 1: User Credentials
+
+```http
+POST /api/auth/login
+Content-Type: application/json
+
+{
+  "email": "user@company.com",
+  "password": "securePassword123"
+}
+```
+
+### Step 2: Server Validates
+
+1. Find user by email
+2. Verify password hash (bcrypt)
+3. Check account status
+4. Load company memberships
+
+### Step 3: Token Generation
+
+**Access Token (JWT)**
+- Short-lived: 15 minutes
+- Contains: user ID, company ID, roles
+- Sent in response body
+
+**Refresh Token (HttpOnly Cookie)**
+- Long-lived: 7 days
+- Contains: user ID, token family ID
+- Set as HttpOnly, Secure, SameSite cookie
+
+### Response
+
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIs...",
+  "user": {
+    "id": 123,
+    "email": "user@company.com",
+    "name": "John Doe",
+    "companies": [
+      { "id": 146, "name": "Acme Corp", "roles": ["Admin"] }
+    ]
+  }
+}
+```
+
+Plus Set-Cookie header for refresh token.
+
+## Token Structure
+
+### Access Token Payload
+
+```json
+{
+  "sub": "123",
+  "email": "user@company.com",
+  "company_id": 146,
+  "roles": ["Admin"],
+  "platform_role": "client",
+  "iat": 1699999000,
+  "exp": 1699999900
+}
+```
+
+### Key Claims
+
+| Claim | Description |
+|---|---|
+| sub | User ID |
+| company_id | Active company |
+| roles | Company-specific roles |
+| platform_role | Platform-wide role (admin/consultant/client) |
+| exp | Expiration timestamp |
+
+## Token Refresh
+
+### Automatic Refresh
+
+Frontend proactively refreshes 30 seconds before expiry:
+
+```typescript
+// Frontend checks every minute
+const checkTokenExpiry = () => {
+  const payload = decodeJwt(token);
+  const expiresIn = payload.exp * 1000 - Date.now();
+
+  if (expiresIn < 30000) {
+    refreshToken();
+  }
+};
+```
+
+### Refresh Endpoint
+
+```http
+POST /api/auth/refresh
+Cookie: refresh_token=...
+```
+
+Response:
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIs..."
+}
+```
+
+New refresh cookie also set.
+
+### Token Rotation
+
+Each refresh generates a new refresh token, invalidating the old one. This prevents token theft attacks.
+
+## Using Tokens
+
+### API Requests
+
+```http
+GET /api/tables/products
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+X-Company-ID: 146
+```
+
+### Backend Validation
+
+```javascript
+// middleware/auth.js
+const authenticateUserToken = async (req, res, next) => {
+  const token = req.headers.authorization?.replace('Bearer ', '');
+
+  if (!token) {
+    return res.status(401).json({ error: 'No token provided' });
+  }
+
+  try {
+    const payload = jwt.verify(token, process.env.JWT_SECRET);
+    req.user = payload;
+
+    // Validate company access
+    const companyId = req.headers['x-company-id'];
+    if (companyId && companyId !== String(payload.company_id)) {
+      // Verify user has access to requested company
+      const hasAccess = await checkCompanyAccess(payload.sub, companyId);
+      if (!hasAccess) {
+        return res.status(403).json({ error: 'Access denied' });
+      }
+    }
+
+    next();
+  } catch (error) {
+    return res.status(401).json({ error: 'Invalid token' });
+  }
+};
+```
+
+## Platform Roles
+
+### Role Hierarchy
+
+| Role | Description | Access |
+|---|---|---|
+| admin | Platform administrator | Everything |
+| consultant | Developer/consultant | Developer tools, Marketplace, no company management |
+| client | Regular user | Basic access, own companies only |
+
+### Checking Platform Role
+
+**Frontend:**
+```typescript
+import { usePlatformRole } from '@/hooks/usePlatformRole';
+
+const { isAdmin, isConsultant, canAccessDeveloperCenter } = usePlatformRole();
+```
+
+**Backend:**
+```javascript
+const platformRole = req.user?.platform_role || 'client';
+
+if (platformRole !== 'admin') {
+  return res.status(403).json({ error: 'Admin only' });
+}
+```
+
+## Company Roles
+
+### Per-Company Permissions
+
+Users can have different roles in different companies:
+
+```
+User 123
+├── Company A: Admin
+├── Company B: Manager
+└── Company C: Viewer
+```
+
+### Role-Based Access
+
+```javascript
+// Check company-specific role
+const companyMembership = await getCompanyMembership(userId, companyId);
+const roles = companyMembership.roles; // ['Admin', 'Sales']
+
+if (!roles.includes('Admin')) {
+  // Limited access
+}
+```
+
+## Security Features
+
+### Password Requirements
+
+- Minimum 8 characters
+- At least one number
+- bcrypt hashing with salt rounds: 12
+
+### Rate Limiting
+
+| Endpoint | Limit |
+|---|---|
+| /auth/login | 5 attempts per minute |
+| /auth/refresh | 10 per minute |
+| /auth/reset-password | 3 per hour |
+
+### Account Lockout
+
+After 5 failed login attempts:
+
+1. Account locked for 15 minutes
+2. Email notification sent
+3. Admin can unlock manually
+
+### Two-Factor Authentication
+
+Optional 2FA using TOTP:
+
+```http
+POST /api/auth/login
+{
+  "email": "user@company.com",
+  "password": "password",
+  "totp_code": "123456"
+}
+```
+
+## Session Management
+
+### Active Sessions
+
+Users can view active sessions:
+
+```http
+GET /api/auth/sessions
+```
+
+Returns:
+```json
+{
+  "sessions": [
+    {
+      "id": "sess_123",
+      "device": "Chrome on Windows",
+      "ip": "192.168.1.1",
+      "lastActive": "2024-01-15T10:30:00Z",
+      "current": true
+    }
+  ]
+}
+```
+
+### Revoking Sessions
+
+```http
+DELETE /api/auth/sessions/sess_123
+```
+
+Or revoke all:
+```http
+DELETE /api/auth/sessions
+```
+
+## API Keys
+
+### For Integrations
+
+API keys provide machine-to-machine authentication:
+
+```http
+GET /api/tables/products
+Authorization: Bearer api_key_xxxxx
+X-Company-ID: 146
+```
+
+### Key Properties
+
+| Property | Description |
+|---|---|
+| name | Descriptive name |
+| permissions | read, write, delete |
+| company_id | Bound to company |
+| last_used | Last usage timestamp |
+
+### Creating Keys
+
+```http
+POST /api/keys
+{
+  "name": "My Integration",
+  "company_id": 146,
+  "permissions": ["read", "write"]
+}
+```
+
+## Logout
+
+### Endpoint
+
+```http
+POST /api/auth/logout
+```
+
+Actions:
+1. Invalidate refresh token
+2. Clear refresh cookie
+3. Optionally invalidate all sessions
+
+### Frontend
+
+```typescript
+const logout = async () => {
+  await fetch('/api/auth/logout', { method: 'POST' });
+  clearLocalStorage();
+  redirectToLogin();
+};
+```
+
+## Security Best Practices
+
+### Token Storage
+
+```typescript
+// Good: Store access token in memory only
+let accessToken = null;
+
+// Bad: Store in localStorage (XSS vulnerable)
+localStorage.setItem('token', token);
+```
+
+### HTTPS Only
+
+All production endpoints require HTTPS. HTTP requests are rejected.
+
+### CORS Configuration
+
+```javascript
+const corsOptions = {
+  origin: ['https://app.gogufi.com'],
+  credentials: true, // For cookies
+  methods: ['GET', 'POST', 'PUT', 'DELETE']
+};
+```
+
+### Security Headers
+
+```
+Strict-Transport-Security: max-age=31536000; includeSubDomains
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+X-XSS-Protection: 1; mode=block
+Content-Security-Policy: default-src 'self'
+```
+
+## Error Codes
+
+| Code | Meaning | Action |
+|---|---|---|
+| 401 | Token invalid/expired | Refresh or re-login |
+| 403 | Access denied | Check permissions |
+| 423 | Account locked | Wait or contact admin |
+| 429 | Too many requests | Wait and retry |