Configuration

The IAM service is initialized by calling configuration() with a single typed object. The schema is validated at startup with Zod and any missing or invalid field throws immediately, preventing the service from starting with a broken config.

import { configuration } from '@riavzon/auth'

await configuration({
  store: { /* ... */ },
  password: { pepper: process.env.PEPPER! },
  botDetector: { enableBotDetector: true },
  htmlSanitizer: { IrritationCount: 50, maxAllowedInputLength: 50000 },
  magic_links: { /* ... */ },
  jwt: { /* ... */ },
  email: { resend_key: process.env.RESEND_KEY!, email: '[email protected]' },
})

store

Database connection pools for the main application database and the rate-limiter store. Both pools accept any valid mysql2 PoolOptions object.

store: {
  main: { host: 'localhost', user: 'root', password: 'secret', database: 'auth' },
  rate_limiters_pool: {
    store: { host: 'localhost', user: 'root', password: 'secret', database: 'auth_limiters' },
    dbName: 'auth_limiters',
  },
}

service

Runtime service settings for proxy trust, port binding, and optional HMAC inter-service authentication. This entire section is optional.

password

Controls Argon2id password hashing parameters. The pepper value is combined with the user's password before hashing: rotate it to invalidate all existing hashes.

botDetector

Controls whether the Bot Detector module runs during authentication flows. When enabled, IP geolocation and device fingerprinting data feed directly into anomaly detection. This is a discriminated union keyed on enableBotDetector.

// Passive mode
botDetector: { enableBotDetector: false }

// Enabled with defaults
botDetector: { enableBotDetector: true }

// Enabled with custom settings
botDetector: {
  enableBotDetector: true,
  settings: { banScore: 75, checkers: { enableTorAnalysis: { enable: false } } },
}

Passive mode

Setting enableBotDetector to false does not shut the Bot Detector down. The middleware still runs and maintains its database connection, but it switches to a passive configuration that disables all active scoring:

• All 17 security checkers are disabled (IP checks, geo checks, TOR analysis, browser/device checks, session coherence, velocity fingerprinting, and so on).
• maxScore is raised from 100 to 300, making it virtually impossible for any request to reach the ban threshold.
• restoredReputationPoints drops from 10 to 1, so scores heal much more slowly across requests.
• logLevel changes from info to warn, reducing noise to only warnings.

The bot detector still tracks requests and maintains reputation data in the database. This means you can switch back to active mode at any time without losing historical context. Passive mode is useful during development, initial deployment, or when you want to observe traffic patterns before enforcing scoring rules.

htmlSanitizer

Controls the multi-pass XSS sanitization pipeline applied to all user-supplied strings before they reach the database. See XSS Protection for full details on the sanitization process.

magic_links

Configuration for signed temporary JWT links used in email MFA and password-reset flows. See Magic Links and MFA for usage details.

thresholds

Each threshold object controls how many GET requests (page loads) and POST requests (form submissions) a user can make to a specific magic link flow before the service stops issuing new links.

emailImages

URLs for images embedded in outgoing emails. All fields have default values pointing to the Riavzon media CDN.

paths

Route paths that magic link URLs resolve to on your frontend. All defaults point to /auth/bounce.

notificationEmail

Branding and navigation links included in all system notification emails (login alerts, password-change alerts, etc.).

providers

Defines the OAuth social login providers the service accepts. Each entry maps an incoming OAuth profile to the internal user schema. This field is optional: omit it entirely if your application does not use social login.

Each provider is defined using one of two approaches:

Custom Zod schema: Full control over validation and transformation.

providers: [
  {
    name: 'github',
    schema: z.object({
      id: z.number(),
      login: z.string(),
      email: z.string().email(),
      avatar_url: z.string().url(),
    }),
  },
]

Field-type map: A shorthand that builds the schema automatically from a record of field names to type tokens.

providers: [
  {
    name: 'google',
    useStandardProfile: true,
    fields: {
      sub: 'string',
      email: 'email',
      name: 'safeString',
      picture: 'url?',
    },
  },
]

FieldToken is one of: 'string', 'string?', 'email', 'email?', 'boolean', 'boolean?', 'url', 'url?', 'number', 'number?', 'int', 'int?', 'safeString', 'safeString?'. Append ? to mark a field optional.

See OAuth for a full provider definition example.

trustUserDeviceOnAuth

jwt

Controls both access token and refresh token behavior.

access_tokens

refresh_tokens

See Tokens for full token lifecycle details.

email

Resend API credentials used for all outgoing system and MFA emails.

rate_limiters

Fine-grained rate-limiter configurations for every sensitive endpoint. This entire section is optional, and every individual limiter group within it is also optional. When the section or any group is omitted, the service falls back to built-in defaults. Rate limiting is always active. Every individual limiter within each group shares the same shape:

See Rate Limiting for detailed usage examples, union limiter patterns, and the full schema for each group.

linkVerificationLimiter

Protects /auth/verify-mfa and /auth/reset-password endpoints.

loginLimiters

Protects POST /login.

oauthLimiters

Protects POST /auth/OAuth/:providerName.

signupLimiters

Protects POST /signup.

tempPostRoutesLimiters

Protects temporary POST routes such as email update and custom MFA initiation.

tokenLimiters

Protects the /auth/user/refresh-session rotation route and the /auth/logout route.

initPasswordResetLimiters

Protects POST /auth/forgot-password.

emailMfaLimiters

Protects email MFA sending endpoints.

logLevel