Service Startup

The IAM service ships two entry points. The @riavzon/auth/service export provides a complete standalone server that reads an age-encrypted configuration file, creates the Express application, and begins listening for requests. The @riavzon/auth export provides the same building blocks as individual functions and routers so you can mount them into your own Express application.

Both paths converge on the same core function: bootstrapApp. This function takes a validated configuration object, creates every pool, table, middleware, and route the service needs, and returns a ready to use Express app.

Package Exports

The package exposes two subpath exports:

When you import from @riavzon/auth, nothing boots automatically. When you import from @riavzon/auth/service, the module calls startServer() immediately unless NODE_ENV is test. In production, this is the module you point your container's CMD at.

For a complete list of every export, see the API reference.

startServer

The startServer function is the outermost entry point in standalone mode. It handles configuration loading, application bootstrap, config file cleanup, and HTTP listening.

Startup Flow

import { startServer } from '@riavzon/auth/service'

// In production, this runs automatically.
// In tests (NODE_ENV=test), you call it manually:
await startServer()

bootstrapApp

The core bootstrap function. It accepts a ConfigurationInput object, performs all initialization, and returns an Express Application. Both the standalone server and library consumers use this function.

import { bootstrapApp } from '@riavzon/auth/service'
import type { ConfigurationInput } from '@riavzon/auth'

const app = await bootstrapApp(config)

Bootstrap Sequence

The function executes the following steps in order:

Middleware Stack

The middleware is mounted in a fixed order. Every request passes through each layer sequentially:

Route Groups

After the early health check and service-wide middleware, six route groups are mounted. Five are authenticated or semi-public routers, and the operational config endpoint is mounted afterward as a direct handler.

Public API Verification Route

Handles machine-to-machine API token verification.

This route is mounted before express.json(), cookieParser(), and the bot-detector middleware. It reads the token from the x-api-key header and the required privilege from the privilege query parameter.

Authentication Routes

Handles account creation, login, and OAuth flows.

All three routes enforce a Content-Type: application/json header via the contentType middleware. The json() middleware limits request bodies to 1 KB (4 KB for OAuth) and rejects empty bodies with a 403. Each route also requires the canary_id cookie from the bot-detector and returns 400 if it is missing.

Token Rotation Routes

Handles token refresh and logout.

The acceptCookieOnly middleware enforces that these requests send only cookies: no JSON body, no query string, and no Content-Type header. This prevents CSRF attacks by ensuring the request cannot carry attacker-controlled data beyond the browser's automatic cookie attachment.

Magic Link Routes

Handles MFA verification, password reset, custom MFA flows, and email changes.

Custom MFA and email update routes require a valid access token, refresh token, fingerprint, and a checkForActiveMfa pass before protectRoute runs full anomaly detection on these requests.

BFF Access Routes

Backend-for-Frontend routes used by your application server to verify user sessions.

Both routes require an access token (Authorization: Bearer header), a refresh token (session cookie), and a valid fingerprint. The routes also call checkForActiveMfa before protectRoute performs full JWT verification and anomaly detection.

API Token Management Routes

Handles authenticated creation and management of API tokens.

All API token management routes require requireAccessToken, requireRefreshToken, getFingerPrint, checkForActiveMfa, and protectRoute. The POST routes also enforce contentType('application/json') and express.json({ limit: '1kb' }). The GET /api/manage/list-metadata branch skips the JSON guards because it does not accept a request body.

Operational Config Endpoint

A single endpoint mounted outside the route groups:

This endpoint is restricted by physical IP address. It compares req.socket.remoteAddress against service.clientIp or service.proxy.ipToTrust. Only the configured trusted client can access it.

Terminal Handlers

Two handlers are registered after all routes:

The error handler logs the full error via pino before sending the response. It picks the status code from the current res.statusCode if it is above 415, otherwise defaults to 500.

Configuration

The configuration object is validated at startup by a strict Zod schema. Every field is type-checked at runtime. If validation fails, the process exits with a detailed error showing which fields failed and why.

The schema covers database connections, JWT settings, password hashing, bot detection, rate limiting, magic links, OAuth providers, email credentials, and standalone server options. Each section is documented in its own essentials page, and the complete schema reference is available in the Configuration reference.

Docker Deployment

The standalone service is designed to run as a Docker container with encrypted configuration.

Container Architecture

The Dockerfile uses a multi-stage build:

Entrypoint Flow

The container entrypoint is decrypt.sh, which runs before the main process:

Health Check

Docker runs a health check every 30 seconds:

http.request({ host: '127.0.0.1', port: 10000, path: '/health', timeout: 2000 })

The check hits GET /health on localhost. A 2xx or 401 response means the service is healthy. The 401 case covers scenarios where HMAC is enabled but the health check runs without headers. Because the HMAC middleware skips localhost health checks, this typically returns 200.

Background Tasks

After the server starts listening, startServer schedules three recurring background tasks:

Each task runs with nice -n 19 (lowest CPU priority) to minimize impact on request handling. Tasks are scheduled with setTimeout and reschedule themselves after completion, so the interval measures the gap between the end of one run and the start of the next.

Library Integration

When using @riavzon/auth as a library in your own Express application, you skip startServer and either call bootstrapApp or mount the individual pieces yourself.

Using bootstrapApp

The simplest integration. Provides the full IAM service as a sub-application:

import express from 'express'
import { bootstrapApp } from '@riavzon/auth/service'

const mainApp = express()

const authApp = await bootstrapApp({
  store: { main: { host: 'localhost', ... }, rate_limiters_pool: { store: { host: 'localhost', ... }, dbName: 'rate_limiters' } },
  password: { pepper: 'your-pepper' },
  botDetector: { enableBotDetector: false },
  htmlSanitizer: {},
  magic_links: { jwt_secret_key: '...', domain: 'https://example.com', notificationEmail: { ... } },
  jwt: { jwt_secret_key: '...', access_tokens: {}, refresh_tokens: { refresh_ttl: 604800000, domain: 'example.com', MAX_SESSION_LIFE: 2592000000, maxAllowedSessionsPerUser: 5, byPassAnomaliesFor: 86400000 } },
  email: { resend_key: '...', email: '[email protected]' },
})

mainApp.use('/auth', authApp)
mainApp.listen(3000)

Using Individual Routers

For more control, call configuration() to initialize the pools and config, then mount only the routers you need:

import express from 'express'
import cookieParser from 'cookie-parser'
import {
  configuration,
  authenticationRoutes,
  tokenRotationRoutes,
  magicLinks,
  bffAccessRoute,
  apiVerificationRoute,
  apiProtectedRoutes,
} from '@riavzon/auth'

const app = express()

await configuration({
  store: { ... },
  password: { pepper: '...' },
  // ... rest of config
})

// Mount only what you need
app.use(apiVerificationRoute())
app.use(cookieParser())
app.use(authenticationRoutes)
app.use(tokenRotationRoutes)
app.use(magicLinks)
app.use(bffAccessRoute)
app.use(apiProtectedRoutes())

app.listen(3000)

CLI Initialization

The package also exposes a CLI binary (auth) and an initAuthData function for one-time setup tasks like creating database tables and downloading the disposable email list:

import { initAuthData } from '@riavzon/auth'

await initAuthData(config)

Or from the command line:

npx auth ./config.json

This runs configuration(), bot-detector setup, makeTables(), createTables(), and the disposable email LMDB download in sequence.

Complete Route Map

For reference, here is every route the IAM service registers:

Summary