skip to content

In NestJS 12's AuthenticationModule.forRoot(), why is session: { idleTtl: 3600 } a bug, and what else does the module reject at startup?

level: middleimportance: nice to knowfreq 15%

answer

  1. not the unit @nestjs/jwt uses
  2. a string with a unit
  3. touchInterval defaults to one minute
  4. values only, no classes

basics

~20 s

AuthenticationModule.forRoot() reads numeric lifetimes as milliseconds, so idleTtl: 3600 is 3.6 seconds: the module warns, then refuses to start because the one-minute touchInterval is not shorter. Unknown keys and features missing handlers also fail startup.

solid answer

~40 s

In NestJS 12's `AuthenticationModule.forRoot()`, lifetimes are milliseconds or strings such as `'15m'` and `'14d'`, unlike `@nestjs/jwt`, which counts seconds. So `idleTtl: 3600` means 3.6 seconds. The module logs a warning for any numeric lifetime under a minute and suggests `'1h'`; here startup then fails, because `session.touchInterval` defaults to `'1m'` and must be shorter than `idleTtl`. The options are values only: a `providers` or `stores` key fails with a hint that those classes register themselves, `isGlobal` and `globalGuard` returned from a `forRootAsync()` factory fail because they belong at the top level, a feature such as `passwordReset` without its registered handler fails, and so does an out-of-range value, including `NaN` from an unset environment variable. Defaults worth knowing: `absoluteTtl` `'7d'`, `idleTtl` `'1d'`, cookie `__Host-sid`.

code

typescript · 15 lines
typescript
import { Module } from '@nestjs/common';
import { AuthenticationModule } from '@nestjs/authentication';

@Module({
  imports: [
    AuthenticationModule.forRoot({
      session: {
        absoluteTtl: '14d',
        idleTtl: '3d',
        touchInterval: '5m',
      },
    }),
  ],
})
export class AppModule {}

go deeper

for a junior

Recall that lifetimes are milliseconds or strings with a unit, and that providers and stores never go into the forRoot() options.

for a middle

Explain why 3600 warns and then fails via the touchInterval rule, and list which mistakes fail startup versus only log a warning.

for a senior

Show you would parse environment values before forRootAsync(), read the startup log in review, and treat a warned lifetime as a release blocker.

for a principal

Argue for a team convention of unit-bearing strings and validated configuration, since a millisecond slip on a token lifetime ships silently.

## Values only: what forRoot() takes `AuthenticationModule.forRoot()` in NestJS 12's `@nestjs/authentication` takes **plain values**: lifetimes, secrets, cookie attributes, the URLs that emails link to. No class goes in the options. Credential providers register with `AuthenticationRegistry`, feature handlers with `registry.registerHandler()`, and stores with `AuthenticationStorage.registerSource()`, each from its own constructor. `forRootAsync({ inject, useFactory })` returns the same options from a factory, for values read from configuration. Two switches sit outside the options object: `isGlobal` (default `true`) and `globalGuard` (default `true`). With `forRootAsync()` they go at the top level, next to `useFactory`, because they decide what the module registers. ## Lifetimes are milliseconds or strings Every lifetime option accepts a number of **milliseconds** or a string such as `'30s'`, `'15m'`, `'1h'` or `'14d'`, up to 100 years. That differs from `@nestjs/jwt`, which counts seconds, and the difference is a classic slip: ```typescript AuthenticationModule.forRoot({ session: { idleTtl: 3600, // 3.6 seconds, not one hour }, }); ``` The module checks lifetimes at startup. For any numeric lifetime between zero and one minute it logs a warning that names the option and guesses what was meant: ```plaintext `session.idleTtl` is 3600 milliseconds. Numeric lifetimes are milliseconds, not seconds as in @nestjs/jwt: did you mean '1h'? ``` In this particular case the app does not even start. Activity is written to the session store at most once per `session.touchInterval`, whose default is `'1m'`, and the session service refuses a `touchInterval` that is not shorter than `idleTtl` (unless `idleTtl` is `0`, which turns the idle timeout off), because active users would be signed out as idle. A 3.6-second idle timeout is shorter than one minute, so startup fails with a `TypeError` naming both values. Write `idleTtl: '1h'` and both problems disappear. ## The session defaults | Option | Default | Meaning | | --- | --- | --- | | `session.absoluteTtl` | `'7d'` | longest a session lives, however active | | `session.idleTtl` | `'1d'` | idle timeout, slid forward by activity; `0` turns it off | | `session.touchInterval` | `'1m'` | how often activity is written, at most | | `session.cookieName` | `__Host-sid` | `sid` when the cookie settings rule out the `__Host-` prefix | | `session.cookie` | `secure: true`, `sameSite: 'lax'`, `path: '/'` | `HttpOnly` is always set | The idea behind an idle clock and an absolute clock is covered with session lifecycles in the authentication material; what matters here is how Nest spells and checks them. ## What fails startup outright The module would rather refuse to boot than run misconfigured. Each of these stops the app at startup: - **A key that is not an option.** `providers`, `stores` or a handler name such as `passwordResetHandler` fails with a hint saying where that thing registers now; a typo fails with the list of real options. - **`isGlobal` or `globalGuard` returned by a `forRootAsync()` factory**: they belong at the top level. - **A feature without its handler, or the reverse.** `emailVerification`, `passwordReset`, `magicLink` and `oidc` each need both the option and a handler registered under that name. - **A value out of range**, including the `NaN` that `Number()` makes of an unset environment variable, and any lifetime longer than 100 years. - **`touchInterval` not shorter than `idleTtl`**, as above. By contrast, a **short numeric lifetime alone is only a warning**: `session: { absoluteTtl: 30000 }` starts, and every session ends after 30 seconds instead of the 500 minutes someone meant. ## Habits that avoid the trap 1. Write every lifetime as a string with a unit, even where a number would be legal. 2. In `forRootAsync()`, parse environment variables explicitly and fail early on missing ones, so `NaN` never reaches the module. 3. Read the startup log: the module prints warnings and the provider chain there, and a reviewer can spot `3600` beside the word milliseconds. 4. Keep classes out of the options object; if you find yourself passing one, it should be registering itself instead. 5. Set lifetimes per environment through `forRootAsync()` rather than editing literals, so a test value such as a ten-second session never ships by accident. The pattern is consistent: the configuration mistakes the module can detect are checked once, when it boots, and either logged or refused before the first request arrives.

  • Where do isGlobal and globalGuard go when the options come from forRootAsync()?
    At the top level of `forRootAsync()`, next to `useFactory` and `inject`, not in the object the factory returns. They decide which providers the module registers, so they must be known before the factory runs; returning them from the factory fails at startup with a message saying so.
  • Does session: { absoluteTtl: 30000 } stop the app from starting?
    No. A short numeric lifetime on its own only logs a warning, here suggesting `'500m'`. The app starts and signs every session out after 30 seconds, so the warning in the startup log is the only signal. `session.idleTtl` is special only because the default `touchInterval` must be shorter than it.

  • Lifetimes in forRoot() are seconds, as in @nestjs/jwt.
  • Credential providers and stores are passed as classes in the forRoot() options.
  • An unknown option key is ignored silently.
  • A short numeric lifetime always stops the app at startup.
  • globalGuard can be returned from the forRootAsync() factory like any other option.

Assumes NestJS 12: the first-party @nestjs/authentication package declares @nestjs/common and @nestjs/core 12 as peer dependencies and is taught by the v12 security docs.