Architecture

​

Overview

​

Technology Stack

​

Core Components

​

Authentication Flow

​

Password-Based Authentication

​

OAuth Flow

​

JWT Token Structure

​

Token Payload

{
  "sub": "user_id_uuid",
  "email": "user@example.com",
  "role": "authenticated",
  "iat": 1704067200,
  "exp": 1704672000,
  "iss": "insforge",
  "aud": "insforge-api"
}

​

Token Claims

​

Security Features

​

API Endpoints

​

Authentication Endpoints

​

OAuth Endpoints

​

Admin Endpoints

​

OAuth Provider Configuration

​

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

​

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

// 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

​

Environment Variables