Auth Overview

Documentation Index

Fetch the complete documentation index at: https://docs.modelence.com/llms.txt

Use this file to discover all available pages before exploring further.

​

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 and error rendering components for your authentication flow
• Rate Limiting - Built-in protection against brute force attacks
• Google Sign-In - OAuth authentication with Google accounts
• GitHub Sign-In - OAuth authentication with GitHub accounts

​

Where to configure what

• auth: { ... } — authentication lifecycle: validation hooks (validateSignup, validateProfileUpdate), event callbacks (onAfterLogin, onAfterSignup, onAfterEmailVerification, …), generateHandle, OAuth linking behavior, and rateLimits. See AuthConfig and Hooks.
• email: { ... } — email delivery: the email provider, sender address, and per-flow templates/subjects/redirect URLs for verification and passwordReset. See Email Configuration.

​

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

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

​

OAuth Account Linking

• 'manual' (default) - The OAuth sign-in is rejected with an error: “User with this email already exists. Please log in instead.” The user must log in with their existing password first and link the provider deliberately.
• 'auto' - The OAuth provider is automatically linked to the existing account, but only when both the OAuth-provided email is verified by the provider and the matching email on the existing account is also marked verified locally. This dual-verification requirement prevents pre-registration account takeover (e.g., someone registering a password account against an email they don’t own, then waiting for the real owner to sign in via OAuth). When auto-linking succeeds, missing firstName, lastName, and avatarUrl fields are backfilled from the provider profile.

​

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: 'test@example.com',
  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);
  }
}

​

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