Auth Overview

Modelence provides a comprehensive built-in authentication system with support for email/password authentication, email verification, password reset, and session management. This guide explains how authentication works in Modelence and how to implement it in your application.

Overview

Modelence authentication includes:

• Email/Password Authentication - User signup and login with email and password
• Session Management - Secure session handling with automatic token rotation
• User Management - User profile and role management
• Email Verification - Optional email verification for new signups
• Password Reset - Secure password reset flow with email tokens
• Hooks - Add custom handlers that run after login or signup
• Rate Limiting - Built-in protection against brute force attacks
• Google Sign-In - OAuth authentication with Google accounts

How Authentication Works

Session Management

When a user visits your application, Modelence automatically creates a session:

1. Session Creation - A secure session token is generated using cryptographically random bytes
2. Token Storage - The session token is stored in the database and sent to the client
3. Automatic Expiration - Sessions expire after 7 days of inactivity
4. Heartbeat Updates - Active sessions are automatically renewed through periodic heartbeat requests

Sessions are stored in the _modelenceSessions collection and tracked with the following properties:

{
  authToken: string;      // Secure random token
  createdAt: Date;        // Session creation timestamp
  expiresAt: Date;        // Automatic expiration date
  userId: ObjectId | null; // Associated user (null for guest sessions)
}

User Authentication Flow

Signup Process

When a user signs up with email and password:

1. Validation - Email format and password strength are validated
2. Duplicate Check - System checks if email already exists
3. Validate Signup (Optional) - If provided, validates signup using validateSignup hook
4. Password Hashing - Password is securely hashed using bcrypt (never stored in plain text)
5. User Creation - User record is created in the _modelenceUsers collection
6. Session Linking - The session is linked to the new user
7. Email Verification (Optional) - If enabled, a verification email is sent

Login Process

When a user logs in:

1. Credential Verification - Email and password are validated against stored credentials
2. Session Update - Current session is linked to the authenticated user
3. User Data - User information is returned to the client
4. State Update - Client-side session state is updated

Basic Implementation

Client-Side Usage

Signup

import { signupWithPassword } from 'modelence/client';

async function handleSignup(email: string, password: string) {
  try {
    await signupWithPassword({ email, password });
    // User is now signed up
    // If email verification is disabled, user is automatically logged in
  } catch (error) {
    console.error('Signup failed:', error.message);
  }
}

// You can also pass optional profile fields during signup
await signupWithPassword({
  email: '[e-mail]',
  password: 'securepassword',
  firstName: 'John',
  lastName: 'Doe',
  avatarUrl: 'https://example.com/avatar.jpg',
  handle: 'johndoe',
});

Login

import { loginWithPassword } from 'modelence/client';

async function handleLogin(email: string, password: string) {
  try {
    const user = await loginWithPassword({ email, password });
    console.log('Logged in as:', user.handle);
  } catch (error) {
    console.error('Login failed:', error.message);
  }
}

Logout

import { logout } from 'modelence/client';

async function handleLogout() {
  await logout();
  // User is now logged out
}

Update Profile

import { updateProfile } from 'modelence/client';

async function handleUpdateProfile() {
  try {
    const user = await updateProfile({
      firstName: 'John',
      lastName: 'Doe',
      avatarUrl: 'https://example.com/avatar.jpg',
      handle: 'johndoe',
    });
    console.log('Profile updated:', user.handle);
  } catch (error) {
    console.error('Update failed:', error.message);
  }
}

All fields are optional — pass only the ones you want to update. Modelence automatically updates the user in useSession().

Accessing Current User

import { useSession } from 'modelence/client';

function MyComponent() {
  const { user } = useSession();

  if (!user) {
    return <div>Please log in</div>;
  }

  return <div>Welcome, {user.handle}!</div>;
}

API Reference

Client Functions

• signupWithPassword - Sign up with email and password
• loginWithPassword - Log in with email and password
• logout - Log out current user
• useSession - Access current user session
• verifyEmail - Verify email with token
• sendResetPasswordToken - Request password reset
• resetPassword - Reset password with token

Server Types

• AuthConfig - Authentication configuration
• UserInfo - User information type
• dbUsers - User database collection

Error Types

• AuthError - Authentication errors
• ValidationError - Validation errors
• RateLimitError - Rate limit errors