Auth Hooks - Modelence

The AuthConfig type provides hooks for authentication events. Configure these in your startApp call under the auth: key.

Validation Hooks

`validateSignup`

Called before a new user is created during email/password signup. Use this to enforce custom validation rules on signup data. Throw an error to reject the signup.

import { startApp } from 'modelence/server';

startApp({
  auth: {
    validateSignup: ({ email, firstName, lastName, password, handle, avatarUrl }) => {
      // Custom validation logic
      if (password.length < 12) {
        throw new Error('Password must be at least 12 characters');
      }
      if (!firstName) {
        throw new Error('First name is required');
      }
    },
  },
});

Props:

Property	Type
`email`	`string`
`password`	`string`
`firstName`	`string \| undefined`
`lastName`	`string \| undefined`
`avatarUrl`	`string \| undefined`
`handle`	`string \| undefined`

Returns: void | Promise<void>

`onBeforeSignup`

Available since modelence@0.17.0.

Called after validateSignup and the built-in disposable-email check, but before the user document is inserted. Use this to plug in a custom domain-policy check (e.g. a tenant-specific email-domain verification service) without disabling the built-in disposable-email check. Throw an error to reject the signup — the thrown error is re-thrown to the caller and onSignupError fires. Currently only invoked for 'email' provider signups. OAuth signups are not gated because OAuth providers (Google, GitHub, etc.) do not issue disposable accounts.

import { startApp } from 'modelence/server';

startApp({
  auth: {
    onBeforeSignup: async ({ email, firstName, lastName, handle, provider, connectionInfo }) => {
      const domain = email.split('@')[1];
      const allowed = await isAllowedDomain(domain);
      if (!allowed) {
        throw new Error(`Signups from ${domain} are not allowed`);
      }
    },
  },
});

To replace the built-in disposable-email check entirely with your own logic, set allowDisposableEmails: true (also available since modelence@0.17.0) and enforce your policy in onBeforeSignup.

startApp({
  auth: {
    allowDisposableEmails: true,
    onBeforeSignup: async ({ email }) => {
      const verdict = await classifyEmailDomain(email);
      if (verdict === 'disposable') {
        throw new Error('Disposable email addresses are not allowed');
      }
    },
  },
});

Props:

Property	Type
`email`	`string`
`firstName`	`string \| undefined`
`lastName`	`string \| undefined`
`handle`	`string \| undefined`
`provider`	`'email'`
`connectionInfo`	`ConnectionInfo \| undefined`

Returns: void | Promise<void>

`validateProfileUpdate`

Called before a user’s profile is updated. Use this to enforce custom validation rules on profile updates. Throw an error to reject the update.

startApp({
  auth: {
    validateProfileUpdate: ({ firstName, lastName, avatarUrl, handle }) => {
      if (handle && handle.length < 3) {
        throw new Error('Handle must be at least 3 characters');
      }
    },
  },
});

Props:

Property	Type
`firstName`	`string \| undefined`
`lastName`	`string \| undefined`
`avatarUrl`	`string \| undefined`
`handle`	`string \| undefined`

Returns: void | Promise<void>

Custom Handle Generation

`generateHandle`

By default, handles are derived from the user’s email address. This hook lets you generate custom handles based on the user’s email and profile information.

startApp({
  auth: {
    generateHandle: ({ email, firstName, lastName }) => {
      // Generate a custom handle
      if (firstName && lastName) {
        return `${firstName.toLowerCase()}-${lastName.toLowerCase()}`;
      }
      return email.split('@')[0];
    },
  },
});

Props:

Property	Type
`email`	`string`
`firstName`	`string \| undefined`
`lastName`	`string \| undefined`

Returns: string | Promise<string> — The generated handle. If the handle conflicts with an existing one, Modelence will automatically append a numeric suffix.

Auth Events

startApp({
  auth: {
    onAfterLogin: ({ user, provider, session, connectionInfo }) => {
      // Called after successful login
      console.log(`${user.handle} logged in via ${provider} from ${connectionInfo.ip}`);
    },
    onLoginError: ({ error, provider, session, connectionInfo }) => {
      // Called when login fails
      console.error('Login error:', error.message);
    },
    onAfterSignup: ({ user, provider, session, connectionInfo }) => {
      // Called after successful signup
      // Perfect place to send welcome emails or analytics
    },
    onSignupError: ({ error, provider, session, connectionInfo }) => {
      // Called when signup fails
      console.error('Signup error:', error.message);
    },
    onAfterEmailVerification: ({ user, session, connectionInfo }) => {
      // Called after successful email verification
    },
    onEmailVerificationError: ({ error, session, connectionInfo }) => {
      // Called when email verification fails
    },
  },
});

Error Rendering

`errorComponent`

Use errorComponent to customize how OAuth authentication errors are rendered. By default, OAuth errors are returned as JSON. Providing errorComponent allows you to return a custom HTML response instead. This is useful when OAuth flows are triggered in a browser context.

startApp({
  auth: {
    errorComponent: ({ error, statusCode }) => {
      // Safely escape the error string to prevent XSS vulnerabilities
      const escapeHtml = (str: string | number) => String(str).replace(/[&<>"']/g, m => ({
        '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#039;'
      })[m as any] || m);

      return `
        <html>
          <body>
            <h1>Error ${escapeHtml(statusCode)}</h1>
            <p>${escapeHtml(error)}</p>
          </body>
        </html>
      `;
    },
  },
});

Full Example

import { startApp } from 'modelence/server';

startApp({
  auth: {
    validateSignup: ({ email, password, firstName }) => {
      if (!firstName) {
        throw new Error('First name is required');
      }
    },
    validateProfileUpdate: ({ handle }) => {
      if (handle && !/^[a-z0-9-]+$/.test(handle)) {
        throw new Error('Handle can only contain lowercase letters, numbers, and hyphens');
      }
    },
    onBeforeSignup: async ({ email }) => {
      const domain = email.split('@')[1];
      if (domain === 'blocked.example') {
        throw new Error(`Signups from ${domain} are not allowed`);
      }
    },
    generateHandle: ({ email, firstName, lastName }) => {
      if (firstName && lastName) {
        return `${firstName}-${lastName}`.toLowerCase();
      }
      return email.split('@')[0];
    },
    errorComponent: ({ error, statusCode }) => {
      const escapeHtml = (str: string | number) => String(str).replace(/[&<>"']/g, m => ({
        '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#039;'
      })[m as any] || m);
      return `<html><body><h1>Error ${escapeHtml(statusCode)}</h1><p>${escapeHtml(error)}</p></body></html>`;
    },
    onAfterSignup: ({ user }) => {
      console.log('Welcome!', user.handle);
    },
    onAfterLogin: ({ user, provider }) => {
      console.log(`${user.handle} logged in via ${provider}`);
    },
  },
});

​Validation Hooks

​validateSignup

​onBeforeSignup

​validateProfileUpdate

​Custom Handle Generation

​generateHandle

​Auth Events

​Error Rendering

​errorComponent

​Full Example

Validation Hooks

`validateSignup`

`onBeforeSignup`

`validateProfileUpdate`

Custom Handle Generation

`generateHandle`

Auth Events

Error Rendering

`errorComponent`

Full Example