Auth Overview

​

Overview

• 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

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

{
  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

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

​

Login Process

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);
  }
}

​

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
}

​

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