AuthModule

The AuthModule is the server-side module that orchestrates authentication. It is responsible for token generation, validation, and exposing the authentication API.

import { AuthModule } from '@archibald/auth';

new AuthModule(OPTIONS);

Options

• Type: AuthModuleOptions

The AuthOptions object has the following properties:

Name	Type	Description
providers	AuthProvider[]	✔️ List of authentication providers.
options	() => AuthOptions	✔️ Dynamic accessor returning the options below. Must be a function — a static object throws when multi-country support is enabled.

strategy

Property	Type	Description
type	'cookie' | 'header'	Defines how tokens are sent. Default 'cookie'.
loadUserThroughAPI	boolean	Whether to load user data through a backend API on every request.

token

Property	Type	Description
secret	string	✔️ The primary JWE encryption secret. Must be exactly 32 characters — the module refuses to start otherwise.
secret_rotation	string	Optional rotation secret, tried on decryption failure (zero-downtime secret rotation).
expirationTime	string | number	TTL for the session token. Default '5m'.
compress	boolean	Whether to compress the token payload. Default false.
filter	(user) => DefaultTokenUser	Selects which user fields are embedded in the token. Default: identity.
cookie	object	Cookie strategy only: cookie flags plus expiresIn (default '10m', sameSite: 'lax').

refresh

Property	Type	Description
secret	string	✔️ Secret for the refresh token (also 32 characters).
secret_rotation	string	Optional rotation secret.
expirationTime	string | number	TTL for the refresh token. Default '1y'.
cookie	object	Cookie strategy only: cookie flags plus expiresIn (default '1y', sameSite: 'lax').

note

A legacy flat form (LegacyAuthModuleOptions, options spread at the top level next to providers) is still accepted. userCacheTime is not an AuthModule option — it belongs to the client-side SessionClient.

Endpoints Provided

Route paths are relative to your API schema (with the template's app.api config: /api/v2/...). Login-related routes are registered conditionally based on app.authentication.whitelistedProtocols — see OIDC Login Flow.

Method	Path	Registered when	Purpose
POST	auth/login	'password' whitelisted	Password login (deprecated since v9).
GET	auth/login	'oidc' whitelisted	Redirects to the IdP authorize URL.
POST	auth/token	'oidc' whitelisted	Authorization code → token exchange (native flow).
GET	auth/callback	'oidc' whitelisted	Handles the IdP redirect, sets session cookies, redirects to the return path.
POST	auth/refresh	always	Refreshes the session token.
POST	auth/logout	always	Logs out and revokes tokens across all providers.
GET	auth/check	always	Logged-in check (auth mode try).
GET	auth/user	always	Returns the current user's profile data (auth mode required).

The module also registers the jwt, cookie, and header Hapi auth strategies (which is why it must be registered before other modules whose routes reference them), and — in the cookie strategy — transparently refreshes expired sessions inside the auth scheme, re-setting the nct/ncr cookies on the response.

Usage Example

// src/server/module/server.tsx
import { AuthModule } from '@archibald/auth';
import { CommerceUserAuthProvider } from '@archibald/commerce/auth';

export class Server extends CoreServer {
    public async initModules() {
        await this.registerModules([
            new AuthModule({
                providers: [
                    new CommerceUserAuthProvider({
                        config: () => this.configService.get('hybris.api'),
                        credentials: () => this.configService.get('hybris.oauth')
                    })
                ],
                options: () => ({
                    strategy: { type: 'cookie' },
                    token: { secret: this.configService.get('server.credentials.token.secret') },
                    refresh: { secret: this.configService.get('server.credentials.token.secret') }
                })
            })
        ]);
    }
}

Relates to

• AuthService: AuthModule uses the AuthService to handle the core logic of token encryption and provider coordination.
• SessionClient: On the frontend, SessionClient makes requests to the endpoints exposed by AuthModule.
• AuthProvider: AuthModule delegates credential validation to one or more providers.
• ServerContext: Populates the server-side context with session data, accessible via getSession().