Auth Hooks

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 (!firstName) {
        throw new Error('First name is required');
      }
    },
  },
});

Don’t enforce password rules here. validateSignup only runs at signup, so a user could sign up with a compliant password and immediately reset to a weaker one — password reset would only enforce the framework’s built-in 8-character floor. Use validatePassword instead: it runs on every password-setting path.

Props:

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

Returns: void | Promise<void>

validatePassword

Enforces your password policy on every path that sets a password — signup and password reset today, plus any future change-password flow. Throw an error to reject the password; the message is surfaced to the client.

This is the hook to use for password rules. Modelence enforces a built-in floor of 8 characters (and a 128-character ceiling) before calling it, so your hook only needs to add your own rules on top.

import { startApp } from 'modelence/server';

startApp({
  auth: {
    validatePassword: ({ password, email, context }) => {
      if (password.length < 12) {
        throw new Error('Password must be at least 12 characters');
      }
      if (password.toLowerCase().includes(email.split('@')[0])) {
        throw new Error('Password must not contain your email address');
      }
    },
  },
});

The hook runs after the built-in length checks and before the password is hashed. On the reset path it runs before the reset token is consumed, so a user whose password is rejected can retry with the same link.

Props:

Property	Type
password	string	The candidate plaintext password
email	string	Lowercased email of the account the password is set on
context	'signup' | 'reset'	Which flow is setting the password

Returns: void | Promise<void>

Use context when a flow needs different treatment — for example, checking a breach-database only on reset:

validatePassword: async ({ password, context }) => {
  if (password.length < 12) {
    throw new Error('Password must be at least 12 characters');
  }
  if (context === 'reset' && (await isBreachedPassword(password))) {
    throw new Error('This password has appeared in a data breach — pick another');
  }
},

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.

Invoked for 'email' and 'magicLink' 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' | 'magicLink'
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 Handling

OAuth errors surface at the provider callback URL (/api/_internal/auth/...), which is a server route outside your client bundle. Nothing there can render your app’s UI, so by default the user lands on a JSON body with no way back. Two options change that.

oauthErrorRedirectUrl

Use oauthErrorRedirectUrl to send the browser back into your app when a web OAuth flow fails. It accepts a path, resolved against your site URL (MODELENCE_SITE_URL), or an absolute URL. The failure is appended as ?error=<message>&errorCode=<code>, the same contract a mobile flow delivers on its deep link, so your app can show it on a real page.

startApp({
  auth: {
    oauthErrorRedirectUrl: '/login',
  },
});

Then read the params on that page:

import { useSearchParams } from 'react-router';

function LoginPage() {
  const [searchParams] = useSearchParams();
  const oauthError = searchParams.get('error');
  // ...render oauthError inline in the form
}

error is for display and its wording may change. Branch on errorCode (invalid_state, email_exists, account_inactive, …) for anything programmatic.

When both oauthErrorRedirectUrl and errorComponent are set, the redirect wins and errorComponent is not called.

errorComponent (deprecated)

errorComponent is deprecated in favor of oauthErrorRedirectUrl. It renders OAuth errors as a standalone HTML document at the callback URL instead of JSON, which means the page cannot use your app’s UI. It is still honored for existing apps, but is ignored whenever oauthErrorRedirectUrl is set.

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');
      }
    },
    validatePassword: ({ password }) => {
      if (password.length < 12) {
        throw new Error('Password must be at least 12 characters');
      }
    },
    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];
    },
    oauthErrorRedirectUrl: '/login',
    onAfterSignup: ({ user }) => {
      console.log('Welcome!', user.handle);
    },
    onAfterLogin: ({ user, provider }) => {
      console.log(`${user.handle} logged in via ${provider}`);
    },
  },
});