AuthConfig

API Reference / modelence / server / AuthConfig

AuthConfig = object

Defined in: packages/modelence/src/app/authConfig.ts:164

Authentication configuration for the application

Example

import { startApp } from 'modelence/server';
import { time } from 'modelence';

startApp({
  auth: {
    validateSignup: ({ email, firstName, lastName, password, handle, avatarUrl }) => {
      // Validating the signup data
      if (!email || !password) {
        throw new Error('Email and password are required');
      }
    },
    onAfterLogin: ({ user }) => {
      console.log('User logged in:', user.name);
      // Redirect to dashboard
    },
    onLoginError: ({ error }) => {
      console.error('Login failed:', error.message);
      // Show error toast
    },
    onAfterSignup: ({ user }) => {
      console.log('User signed up:', user.email);
      // Send welcome email
    },
    onSignupError: ({ error }) => {
      console.error('Signup failed:', error.message);
    },
    generateHandle: ({ email }) => {
      console.log('Generating handle for:', email);
      // Generate handle
      return 'user123';
    },
  }
});

Properties

Property	Type	Description	Defined in
allowDisposableEmails?	boolean	When true, the built-in disposable-email check is skipped during signup. Defaults to false (built-in check enforced). Set this to true when you want to enforce your own domain-policy logic via onBeforeSignup — for example, a service that classifies domains as public/disposable/custom with its own data sources and cache. Skipping the built-in check without registering an onBeforeSignup hook means disposable emails will be allowed to sign up.	packages/modelence/src/app/authConfig.ts:329
errorComponent?	(props) => string | null | undefined	Customizes how OAuth authentication errors are rendered. By default, OAuth errors are returned as JSON; providing this returns a custom HTML response instead, which is useful when the OAuth flow runs in a browser context. Receives { error, statusCode } and returns an HTML string (or null/undefined to fall back to the default JSON response). Always escape interpolated values to prevent XSS.	packages/modelence/src/app/authConfig.ts:307
generateHandle?	(props) => Promise<string> | string	Custom handle generator. If provided, overrides the default behavior (which derives the handle from the email local-part). Receives { email, firstName?, lastName? } and returns the desired handle synchronously or as a Promise<string>. If the returned handle collides with an existing one, Modelence appends a numeric suffix automatically.	packages/modelence/src/app/authConfig.ts:257
login?	AuthOption	Deprecated Use AuthConfig.onAfterLogin and AuthConfig.onLoginError instead.	packages/modelence/src/app/authConfig.ts:260
magicLink?	object	Enables passwordless magic link authentication. Disabled by default. Requires an email provider and delivery settings under the email option (see EmailConfig.magicLink). Example startApp({ auth: { magicLink: { enabled: true, allowSignup: true }, }, });	packages/modelence/src/app/authConfig.ts:279
magicLink.allowSignup?	boolean	Allows a magic link (or its one-time code) to create an account when the email has no existing one — combined sign-in/sign-up, like OAuth. Disabled by default: unknown emails get the same generic “link sent” response but no email, and no account is ever auto-created.	packages/modelence/src/app/authConfig.ts:287
magicLink.enabled?	boolean	-	packages/modelence/src/app/authConfig.ts:280
oauthAccountLinking?	"auto" | "manual"	Controls how OAuth providers handle existing accounts with matching email. - ‘manual’ (default): Returns an error when an OAuth login matches an existing email. - ‘auto’: Automatically links the OAuth provider to the existing account if the provider email is verified.	packages/modelence/src/app/authConfig.ts:296
onAfterEmailVerification?	(props) => void	Fires after a user’s email is successfully verified (via the verification link or implicitly via password reset). Receives { provider, user, session, connectionInfo }.	packages/modelence/src/app/authConfig.ts:229
onAfterLogin?	(props) => void	Fires after a successful login (email/password or OAuth) once the session has been linked to the user. Receives { provider, user, session, connectionInfo }. Use for analytics, audit logging, or post-login side effects.	packages/modelence/src/app/authConfig.ts:188
onAfterOAuthLink?	(props) => void	Fires after an OAuth provider is linked to an existing account (either automatically when oauthAccountLinking: 'auto' or via an explicit link flow). Receives { provider, user, session, connectionInfo }.	packages/modelence/src/app/authConfig.ts:242
onAfterSignup?	(props) => void	Fires after a successful signup once the user record is created and the session is linked. Receives { provider, user, session, connectionInfo }. Common uses: send welcome email, create default workspace, track activation.	packages/modelence/src/app/authConfig.ts:216
onBeforeSignup?	(props) => void | Promise<void>	Hook fired after validation and the built-in disposable-email check, but before the new user document is inserted. Throwing aborts the signup — the thrown error is re-thrown to the caller and onSignupError fires. Use this to plug in a custom domain-policy check (e.g. a tenant-specific email-domain verification service) without having to disable the built-in disposable-email check. Invoked for 'email' and 'magicLink' provider signups. OAuth signups are not gated because OAuth providers (Google, GitHub, etc.) do not issue disposable accounts.	packages/modelence/src/app/authConfig.ts:209
onEmailVerificationError?	(props) => void	Fires when email verification fails (invalid or expired token). Receives { provider, error, session, connectionInfo }.	packages/modelence/src/app/authConfig.ts:235
onLoginError?	(props) => void	Fires when a login attempt fails. Receives { provider, error, session, connectionInfo }. Use for failure analytics or alerting — does NOT change the response sent to the client.	packages/modelence/src/app/authConfig.ts:194
onOAuthLinkError?	(props) => void	Fires when OAuth account linking fails. Receives { provider, error, session, connectionInfo }.	packages/modelence/src/app/authConfig.ts:248
onSignupError?	(props) => void	Fires when a signup attempt fails (validation, duplicate email, etc.). Receives { provider, error, session, connectionInfo }. Use for failure analytics — does NOT change the response sent to the client.	packages/modelence/src/app/authConfig.ts:223
rateLimits?	AuthRateLimitsConfig	Overrides the built-in rate limits for authentication endpoints. Each rule you provide is merged into the defaults by (bucket, type, window): matching tuples replace the default limit, new tuples are added, and unspecified defaults are preserved. See AuthRateLimitsConfig for full semantics and examples.	packages/modelence/src/app/authConfig.ts:316
signup?	AuthOption	Deprecated Use AuthConfig.onAfterSignup and AuthConfig.onSignupError instead.	packages/modelence/src/app/authConfig.ts:262
validateProfileUpdate?	(props) => void | Promise<void>	Pre-update validation hook. Runs before a user’s profile fields (firstName, lastName, avatarUrl, handle) are written. Throw to reject the update — the thrown message is surfaced to the client. May be async.	packages/modelence/src/app/authConfig.ts:181
validateSignup?	(props) => void | Promise<void>	Pre-signup validation hook. Runs before a new user is created during email/password signup, after format checks but before duplicate detection. Throw to reject the signup — the thrown message is surfaced to the client. Receives the raw signup payload (email, password, and optional firstName, lastName, avatarUrl, handle). May be async.	packages/modelence/src/app/authConfig.ts:173