AuthConfig

API Reference / modelence / server / AuthConfig

AuthConfig = object

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

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:424
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. Deprecated Use AuthConfig.oauthErrorRedirectUrl instead. It sends the browser back into the app, where the error can be shown on a real page with the app’s own UI; this only ever renders a standalone document at the callback URL. Ignored when oauthErrorRedirectUrl is set.	packages/modelence/src/app/authConfig.ts:371
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>. The returned handle must contain only letters, numbers, underscores, and hyphens (matching HANDLE_REGEX). If the returned handle collides with an existing one, Modelence appends a numeric suffix automatically.	packages/modelence/src/app/authConfig.ts:316
login?	AuthOption	Deprecated Use AuthConfig.onAfterLogin and AuthConfig.onLoginError instead.	packages/modelence/src/app/authConfig.ts:319
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:338
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:346
magicLink.enabled?	boolean	-	packages/modelence/src/app/authConfig.ts:339
mobile?	object	Settings for authenticating from a native (React Native / Expo) client. Example startApp({ auth: { mobile: { redirectUrls: ['myapp://auth'] }, }, });	packages/modelence/src/app/authConfig.ts:438
mobile.redirectUrls?	string[]	Deep links the OAuth callback is allowed to redirect a native app back to, e.g. ['myapp://auth']. A sign-in request naming any other target is rejected before the user ever reaches the provider’s consent screen. This is an allowlist because the redirect target decides where an auth flow ends up: without it, a crafted link could point the callback at an attacker-controlled destination. There is no implicit default — mobile OAuth stays disabled until at least one entry is configured here or via the auth.mobile.redirectUrls config value (the two are merged). Entries are matched on scheme, host and path; a request may add query parameters but may not change any of those three.	packages/modelence/src/app/authConfig.ts:453
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:355
oauthErrorRedirectUrl?	string	Where a failed web OAuth flow sends the browser. A path ('/login'), resolved against _system.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 the app can show the message on a real page instead of the raw callback response. OAuth errors surface at the provider callback URL, outside any client bundle, so nothing there can render app UI. Without this (or AuthConfig.errorComponent) the user lands on a JSON body with no way back. When both are set, the redirect wins and errorComponent is not called. error is for display and its wording may change; branch on errorCode. Applies to the provider callback only. A request rejected at the sign-in initiation endpoint (auth not configured, a disallowed mobile redirectUri, a missing codeChallenge) still answers the calling client with JSON, since nothing has left for the provider yet. Example startApp({ auth: { oauthErrorRedirectUrl: '/login', }, });	packages/modelence/src/app/authConfig.ts:402
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:286
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:245
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:299
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:273
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:266
onEmailVerificationError?	(props) => void	Fires when email verification fails (invalid or expired token). Receives { provider, error, session, connectionInfo }.	packages/modelence/src/app/authConfig.ts:292
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:251
onOAuthLinkError?	(props) => void	Fires when OAuth account linking fails. Receives { provider, error, session, connectionInfo }.	packages/modelence/src/app/authConfig.ts:305
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:280
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:411
signup?	AuthOption	Deprecated Use AuthConfig.onAfterSignup and AuthConfig.onSignupError instead.	packages/modelence/src/app/authConfig.ts:321
validatePassword?	(props) => void | Promise<void>	Password policy hook. Runs on every path that sets a password — signup and password reset today, plus any future change-password flow — after the built-in length checks (MIN_PASSWORD_LENGTH..MAX_PASSWORD_LENGTH) and before the password is hashed. Throw to reject the password; the thrown message is surfaced to the client. Prefer this over AuthConfig.validateSignup for password rules. validateSignup only runs at signup, so a policy enforced there alone can be bypassed by signing up with a compliant password and immediately resetting to a weaker one. Receives { password, email, context }, where context is the flow that triggered the check ('signup' or 'reset'). May be async. Example startApp({ auth: { validatePassword: ({ password }) => { if (password.length < 12) { throw new Error('Password must be at least 12 characters'); } }, }, });	packages/modelence/src/app/authConfig.ts:230
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:238
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:200