In NestJS 12's AuthenticationModule.forRoot(), why is session: { idleTtl: 3600 } a bug, and what else does the module reject at startup?
answer
- not the unit @nestjs/jwt uses
- a string with a unit
- touchInterval defaults to one minute
- values only, no classes
basics
~20 sAuthenticationModule.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 sIn 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 linesimport { 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
Recall that lifetimes are milliseconds or strings with a unit, and that providers and stores never go into the forRoot() options.
Explain why 3600 warns and then fails via the touchInterval rule, and list which mistakes fail startup versus only log a warning.
Show you would parse environment values before forRootAsync(), read the startup log in review, and treat a warned lifetime as a release blocker.
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.