insforge 0.3.3 → 1.2.10

package/docs/core-concepts/authentication/architecture.mdx

@@ -0,0 +1,278 @@
+---
+title: Architecture
+description: JWT-based authentication with OAuth providers and session management
+---
+
+## Overview
+
+InsForge implements a modern, secure authentication system using JWT tokens with RSA signing, OAuth provider integration, and database-backed session management.
+
+## Technology Stack
+
+```mermaid
+graph TB
+    Client[Client Application] --> SDK[InsForge SDK]
+    SDK --> AuthAPI[Auth API]
+    
+    AuthAPI --> JWT[JWT Service]
+    AuthAPI --> OAuth[OAuth Providers]
+    AuthAPI --> DB[(PostgreSQL)]
+    
+    OAuth --> Google[Google OAuth 2.0]
+    OAuth --> GitHub[GitHub OAuth]
+    
+    JWT --> Secret[Shared Secret]
+    JWT --> Validation[Token Validation]
+    
+    DB --> Accounts[_accounts Table]
+    DB --> Users[users Table]
+    DB --> OAuth[_account_providers]
+    
+    style Client fill:#1e293b,stroke:#475569,color:#e2e8f0
+    style SDK fill:#1e40af,stroke:#3b82f6,color:#dbeafe
+    style AuthAPI fill:#166534,stroke:#22c55e,color:#dcfce7
+    style JWT fill:#c2410c,stroke:#fb923c,color:#fed7aa
+    style OAuth fill:#6b21a8,stroke:#a855f7,color:#f3e8ff
+    style DB fill:#0e7490,stroke:#06b6d4,color:#cffafe
+    style Secret fill:#991b1b,stroke:#ef4444,color:#fee2e2
+    style Google fill:#4c1d95,stroke:#8b5cf6,color:#ede9fe
+    style GitHub fill:#1e293b,stroke:#64748b,color:#f1f5f9
+    style Validation fill:#991b1b,stroke:#ef4444,color:#fee2e2
+    style Accounts fill:#0e7490,stroke:#22d3ee,color:#cffafe
+    style Users fill:#0e7490,stroke:#22d3ee,color:#cffafe
+    style OAuth fill:#0e7490,stroke:#22d3ee,color:#cffafe
+```
+
+## Core Components
+
+| Component | Technology | Purpose |
+|-----------|------------|---------|
+| **Token Format** | JWT with HS256 | Stateless authentication tokens |
+| **Signing Algorithm** | HMAC-SHA256 | Symmetric key signing with shared secret |
+| **Authentication** | Stateless JWT | No server-side session storage |
+| **Password Hashing** | bcryptjs (10 rounds) | Secure password storage |
+| **OAuth Providers** | Google, GitHub, Microsoft, Discord, and more | Social authentication |
+| **Token Expiry** | Fixed | 7 days for user tokens, never for anon tokens |
+
+## Authentication Flow
+
+### Password-Based Authentication
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant SDK
+    participant API
+    participant DB
+    participant JWT
+    
+    Client->>SDK: signUp/signIn(email, password)
+    SDK->>API: POST /api/auth/users or /sessions
+    API->>DB: Verify credentials
+    DB-->>API: User data
+    API->>JWT: Generate token (HS256)
+    JWT-->>API: Signed JWT
+    API-->>SDK: {user, accessToken}
+    SDK-->>Client: Authenticated
+```
+
+### OAuth Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant SDK
+    participant API
+    participant Provider
+    participant DB
+    
+    Client->>SDK: signInWithOAuth(provider)
+    SDK->>API: GET /api/auth/oauth/{provider}
+    API-->>Client: Redirect to provider
+    Client->>Provider: Authorize
+    Provider-->>Client: Callback with code
+    Client->>API: GET /callback?code=xxx
+    API->>Provider: Exchange code for token
+    Provider-->>API: User info
+    API->>DB: Create/update user
+    API->>DB: Link OAuth account
+    API-->>Client: {user, accessToken}
+```
+
+## JWT Token Structure
+
+### Token Payload
+
+```json
+{
+  "sub": "user_id_uuid",
+  "email": "user@example.com",
+  "role": "authenticated",
+  "iat": 1704067200,
+  "exp": 1704672000,
+  "iss": "insforge",
+  "aud": "insforge-api"
+}
+```
+
+### Token Claims
+
+| Claim | Description | Example |
+|-------|-------------|---------|
+| `sub` | Subject (User ID) | UUID format |
+| `email` | User's email | user@example.com |
+| `role` | User role/permissions | authenticated, admin |
+| `iat` | Issued at timestamp | Unix timestamp |
+| `exp` | Expiration timestamp | Unix timestamp |
+| `iss` | Token issuer | insforge |
+| `aud` | Intended audience | insforge-api |
+
+## Security Features
+
+<CardGroup cols={2}>
+  <Card title="HS256 Signing" icon="signature">
+    Tokens signed with HMAC-SHA256 using shared secret key
+  </Card>
+  
+  <Card title="bcrypt Hashing" icon="lock">
+    Passwords hashed with bcryptjs using 10 salt rounds
+  </Card>
+  
+  <Card title="OAuth State" icon="shield-check">
+    CSRF protection via state parameter in OAuth flows
+  </Card>
+  
+  <Card title="Stateless Auth" icon="clock">
+    JWT tokens with built-in expiry, no server-side sessions
+  </Card>
+  
+  <Card title="Token Rotation" icon="arrows-rotate">
+    Support for refresh token rotation (coming soon)
+  </Card>
+  
+  <Card title="Rate Limiting" icon="gauge">
+    Protection against brute force attacks
+  </Card>
+</CardGroup>
+
+## API Endpoints
+
+### Authentication Endpoints
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| POST | `/api/auth/users` | Register new user |
+| POST | `/api/auth/sessions` | Login with email/password |
+| GET | `/api/auth/sessions/current` | Get current user (requires auth) |
+| POST | `/api/auth/admin/sessions` | Admin login (local development) |
+| POST | `/api/auth/admin/sessions/exchange` | Exchange authorization code (cloud platform) |
+
+### OAuth Endpoints
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/api/auth/oauth/:provider` | Initiate OAuth flow for any supported provider |
+| GET | `/api/auth/oauth/:provider/callback` | OAuth callback handler |
+
+### Admin Endpoints
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/api/auth/users` | List all users (admin only) |
+| DELETE | `/api/auth/users` | Delete users (admin only) |
+
+## OAuth Provider Configuration
+
+InsForge supports multiple OAuth providers including Google, GitHub, Microsoft, Discord, LinkedIn, Facebook and more coming soon.
+
+### Example: Google OAuth 2.0
+
+- **Authorization URL**: `https://accounts.google.com/o/oauth2/v2/auth`
+- **Token URL**: `https://oauth2.googleapis.com/token`
+- **Scopes**: `openid`, `email`, `profile`
+- **Required**: Client ID, Client Secret, Redirect URI
+
+### Example: GitHub OAuth
+
+- **Authorization URL**: `https://github.com/login/oauth/authorize`
+- **Token URL**: `https://github.com/login/oauth/access_token`
+- **Scopes**: `read:user`, `user:email`
+- **Required**: Client ID, Client Secret, Redirect URI
+
+## Token Validation
+
+### Validation Steps
+
+1. **Format Check**: Verify JWT structure (header.payload.signature)
+2. **Signature Verification**: Validate with RSA public key
+3. **Expiry Check**: Ensure token hasn't expired
+4. **Issuer/Audience**: Verify iss and aud claims
+5. **User Lookup**: Check user exists in _accounts table
+6. **User Status**: Ensure user account is active
+
+### Middleware Flow
+
+```javascript
+// Simplified validation flow (stateless)
+async function validateToken(token) {
+  // 1. Decode and verify JWT
+  const decoded = jwt.verify(token, publicKey, {
+    algorithms: ['RS256'],
+    issuer: 'insforge',
+    audience: 'insforge-api'
+  });
+  
+  // 2. Check user exists (optional)
+  const user = await db.query(
+    'SELECT * FROM _accounts WHERE id = $1',
+    [decoded.sub]
+  );
+  
+  // 3. Return user context from JWT
+  return {
+    userId: decoded.sub,
+    email: decoded.email,
+    role: decoded.role
+  };
+}
+```
+
+## Security Best Practices
+
+<CardGroup cols={2}>
+  <Card title="HTTPS Only" icon="lock">
+    Always use HTTPS in production to protect tokens in transit
+  </Card>
+  
+  <Card title="Secure Storage" icon="database">
+    Store tokens in httpOnly cookies or secure storage
+  </Card>
+  
+  <Card title="Short Expiry" icon="clock">
+    Use short-lived access tokens with refresh tokens
+  </Card>
+  
+  <Card title="Revocation" icon="ban">
+    Implement token revocation for compromised accounts
+  </Card>
+  
+  <Card title="Password Policy" icon="key">
+    Enforce strong password requirements
+  </Card>
+  
+  <Card title="2FA Support" icon="mobile">
+    Two-factor authentication (coming soon)
+  </Card>
+</CardGroup>
+
+## Environment Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `JWT_SECRET` | RSA private key or secret | Base64 encoded key |
+| `GOOGLE_CLIENT_ID` | Google OAuth client ID | xxx.apps.googleusercontent.com |
+| `GOOGLE_CLIENT_SECRET` | Google OAuth secret | Secret string |
+| `GITHUB_CLIENT_ID` | GitHub OAuth client ID | GitHub app ID |
+| `GITHUB_CLIENT_SECRET` | GitHub OAuth secret | Secret string |
+| `TOKEN_EXPIRY` | Token lifetime | 7d, 24h, 3600 |
+

package/docs/core-concepts/authentication/sdk.mdx

@@ -0,0 +1,414 @@
+---
+title: Authentication SDK Reference
+description: User authentication and profile management with the InsForge SDK
+---
+
+import Installation from '/snippets/sdk-installation.mdx';
+
+<Installation />
+
+## signUp()
+
+Create a new user account with email and password.
+
+### Parameters
+
+- `email` (string, required) - User's email address
+- `password` (string, required) - User's password
+- `name` (string, optional) - User's display name
+
+### Returns
+
+```typescript
+{
+  data: {
+    user: { id, email, name, emailVerified, createdAt, updatedAt },
+    accessToken: string
+  } | null,
+  error: Error | null
+}
+```
+
+### Example
+
+```javascript
+const { data, error } = await insforge.auth.signUp({
+  email: 'user@example.com',
+  password: 'secure_password123',
+  name: 'John Doe'
+})
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "user": {
+      "id": "usr_abc123",
+      "email": "user@example.com",
+      "name": "John Doe",
+      "emailVerified": false,
+      "createdAt": "2024-01-15T10:00:00Z",
+      "updatedAt": "2024-01-15T10:00:00Z"
+    },
+    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+  },
+  "error": null
+}
+```
+
+---
+
+## signInWithPassword()
+
+Sign in an existing user with email and password.
+
+### Parameters
+
+- `email` (string, required) - User's email address
+- `password` (string, required) - User's password
+
+### Returns
+
+```typescript
+{
+  data: {
+    user: { id, email, name, emailVerified, createdAt, updatedAt },
+    accessToken: string
+  } | null,
+  error: Error | null
+}
+```
+
+### Example
+
+```javascript
+const { data, error } = await insforge.auth.signInWithPassword({
+  email: 'user@example.com',
+  password: 'secure_password123'
+})
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "user": {
+      "id": "usr_abc123",
+      "email": "user@example.com",
+      "name": "John Doe",
+      "emailVerified": true,
+      "createdAt": "2024-01-15T10:00:00Z",
+      "updatedAt": "2024-01-15T10:00:00Z"
+    },
+    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+  },
+  "error": null
+}
+```
+
+---
+
+## signInWithOAuth()
+
+Start OAuth authentication flow with supported providers (Google, GitHub, Microsoft, Discord, and more).
+
+### Parameters
+
+- `provider` (string, required) - OAuth provider name (e.g., 'google', 'github', 'microsoft', 'discord')
+- `redirectTo` (string, optional) - URL to redirect after authentication
+- `skipBrowserRedirect` (boolean, optional) - If true, returns OAuth URL without auto-redirecting (for mobile apps)
+
+### Returns
+
+```typescript
+{
+  data: { url?: string, provider?: string },
+  error: Error | null
+}
+```
+
+<Note>
+After OAuth redirect, SDK automatically detects callback parameters and saves session. No manual handling needed.
+</Note>
+
+### Example
+
+```javascript
+// Default: auto-redirect
+await insforge.auth.signInWithOAuth({
+  provider: 'google',
+  redirectTo: 'http://localhost:3000/dashboard'
+})
+// Browser immediately redirects to Google
+
+// skipBrowserRedirect: get URL for manual handling
+const { data } = await insforge.auth.signInWithOAuth({
+  provider: 'google',
+  skipBrowserRedirect: true
+})
+
+window.location.href = data.url // Redirect when ready
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...",
+    "provider": "google"
+  },
+  "error": null
+}
+```
+
+---
+
+## signOut()
+
+Sign out the current user and clear session.
+
+### Parameters
+
+None
+
+### Returns
+
+```typescript
+{
+  error: Error | null
+}
+```
+
+### Example
+
+```javascript
+const { error } = await insforge.auth.signOut()
+```
+
+### Output
+
+```json
+{
+  "error": null
+}
+```
+
+---
+
+## getCurrentUser()
+
+Get authenticated user with profile data from users table.
+
+### Parameters
+
+None
+
+### Returns
+
+```typescript
+{
+  data: {
+    user: { id, email, role },
+    profile: { id, nickname, avatar_url, bio, birthday, ... }
+  } | null,
+  error: Error | null
+}
+```
+
+### Example
+
+```javascript
+const { data, error } = await insforge.auth.getCurrentUser()
+
+if (data) {
+  console.log(data.user.email)        // Auth info
+  console.log(data.profile.nickname)  // Profile from users table
+}
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "user": {
+      "id": "usr_abc123",
+      "email": "user@example.com",
+      "role": "authenticated"
+    },
+    "profile": {
+      "id": "usr_abc123",
+      "nickname": "JohnDoe",
+      "avatar_url": "https://example.com/avatar.jpg",
+      "bio": "Full-stack developer",
+      "birthday": "1990-01-01"
+    }
+  },
+  "error": null
+}
+```
+
+---
+
+## getCurrentSession()
+
+Get current session from local storage (no API call).
+
+### Parameters
+
+None
+
+### Returns
+
+```typescript
+{
+  data: {
+    session: {
+      accessToken: string,
+      user: { id, email, name, ... }
+    } | null
+  },
+  error: Error | null
+}
+```
+
+### Example
+
+```javascript
+const { data, error } = await insforge.auth.getCurrentSession()
+
+if (data.session) {
+  console.log('Token:', data.session.accessToken)
+}
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "session": {
+      "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+      "user": {
+        "id": "usr_abc123",
+        "email": "user@example.com",
+        "name": "John Doe"
+      }
+    }
+  },
+  "error": null
+}
+```
+
+---
+
+## getProfile()
+
+Get any user's public profile by ID.
+
+### Parameters
+
+- `userId` (string, required) - User ID to fetch profile for
+
+### Returns
+
+```typescript
+{
+  data: { id, nickname, avatar_url, bio, birthday, ... } | null,
+  error: Error | null
+}
+```
+
+### Example
+
+```javascript
+const { data: profile, error } = await insforge.auth.getProfile('usr_xyz789')
+
+console.log(profile.nickname)
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "id": "usr_xyz789",
+    "nickname": "JaneDoe",
+    "avatar_url": "https://example.com/jane.jpg",
+    "bio": "Designer and developer",
+    "birthday": "1992-05-15"
+  },
+  "error": null
+}
+```
+
+---
+
+## setProfile()
+
+Update current user's profile in users table.
+
+### Parameters
+
+- `nickname` (string, optional) - User's display name
+- `avatar_url` (string, optional) - Profile picture URL
+- `bio` (string, optional) - User biography
+- `birthday` (string, optional) - Birth date (YYYY-MM-DD format)
+
+### Returns
+
+```typescript
+{
+  data: { id, nickname, avatar_url, bio, birthday, ... } | null,
+  error: Error | null
+}
+```
+
+### Example
+
+```javascript
+const { data: profile, error } = await insforge.auth.setProfile({
+  nickname: 'JohnDev',
+  bio: 'Full-stack developer',
+  avatar_url: 'https://example.com/avatar.jpg'
+})
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "id": "usr_abc123",
+    "nickname": "JohnDev",
+    "avatar_url": "https://example.com/avatar.jpg",
+    "bio": "Full-stack developer",
+    "birthday": null
+  },
+  "error": null
+}
+```
+
+---
+
+## Error Handling
+
+All auth methods return structured errors:
+
+```javascript
+const { data, error } = await insforge.auth.signInWithPassword({
+  email: 'user@example.com',
+  password: 'wrong_password'
+})
+
+if (error) {
+  console.error(error.statusCode)    // 401
+  console.error(error.error)         // 'INVALID_CREDENTIALS'
+  console.error(error.message)       // 'Invalid login credentials'
+  console.error(error.nextActions)   // 'Check email and password'
+}
+```