@nestjs/authentication 0.0.1

package/dist/account/password-reset.service.js

@@ -0,0 +1,204 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var PasswordResetService_1;
+import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
+import { AuthenticationRegistry } from '../services/authentication-registry.service.js';
+import { AuthenticationStorage } from '../storage/authentication.storage.js';
+import { AUTHENTICATION_MODULE_OPTIONS } from '../authentication.constants.js';
+import { TOKEN_PATTERN, randomToken, safeEqual, sha256 } from '../utils/crypto.util.js';
+import { durationOr, hasExpired } from '../utils/duration.util.js';
+import { AuthenticationEvents } from '../events/authentication-events.service.js';
+import { requireUrlOption } from '../utils/options.util.js';
+import { TokenService } from '../jwt/token.service.js';
+import { PasswordHasher, isHashablePassword } from '../services/password-hasher.service.js';
+import { SessionService } from '../session/session.service.js';
+import { SignInService } from '../session/sign-in.service.js';
+import { isMailableEmail, normalizeEmail } from './email.util.js';
+/**
+ * "Forgot your password?": reset links that are 256-bit single-use tokens,
+ * stored hashed, short-lived, and bound to the address they were sent to and
+ * to the password they replace.
+ *
+ * - `request(email)` answers the same way, at once, whether or not the
+ *   address has an account: finding the account, storing the token and
+ *   sending the link happen after it returned, so neither the answer nor
+ *   its timing reveals which addresses are registered. The link goes to the
+ *   address the account has stored, never to the one typed in the form.
+ * - `reset(token, password)` burns the token, stores the new password's
+ *   hash, invalidates the user's other reset links, and ends every session
+ *   and refresh-token family of the user (whoever knew the old password is
+ *   signed out). It also marks the address verified when email
+ *   verification is configured: the link proved it. API keys live in your
+ *   own table: revoke those yourself, on the `password-reset` event.
+ *
+ * Point the link at a page that asks for the new password and POSTs it with
+ * the token: mail scanners and link previews follow GET links.
+ */
+let PasswordResetService = PasswordResetService_1 = class PasswordResetService {
+    constructor(storage, registry, hasher, sessions, tokens, signInService, options, events = new AuthenticationEvents()) {
+        this.storage = storage;
+        this.registry = registry;
+        this.hasher = hasher;
+        this.sessions = sessions;
+        this.tokens = tokens;
+        this.signInService = signInService;
+        this.events = events;
+        this.inFlight = new Set();
+        this.options = options?.passwordReset;
+        if (this.options) {
+            requireUrlOption(this.options.url, 'passwordReset.url', 'the page that receives the link');
+        }
+        this.ttl = durationOr(this.options?.ttl, '1h');
+    }
+    /**
+     * Starts a reset for `email`, if it belongs to an account: the link goes
+     * to `PasswordResetHandler.send()`. Returns at once, before the account is
+     * looked up, so the caller answers every address the same way and in the
+     * same time. Failures are logged, not thrown. On shutdown, the module waits
+     * for the requests in flight.
+     */
+    request(email) {
+        this.feature();
+        const requested = typeof email === 'string' ? normalizeEmail(email) : '';
+        if (!isMailableEmail(requested)) {
+            return;
+        }
+        // The lookup runs once the caller has answered: even a handler that works synchronously
+        // cannot make the answer, or its timing, depend on the account.
+        const work = new Promise((resolve) => setImmediate(resolve))
+            .then(() => this.issue(requested))
+            .catch((error) => PasswordResetService_1.logger.error('A password reset request failed', error instanceof Error ? error.stack : error));
+        this.inFlight.add(work);
+        void work.finally(() => this.inFlight.delete(work));
+    }
+    /**
+     * Sets a new password with a reset token. `null` (and nothing changed)
+     * for an unknown, used or expired token, and for one whose account
+     * changed its address or password since the link was sent. `null` too,
+     * before the token is looked up (so the link still works), for a password
+     * `PasswordHasher` refuses: not a string, empty, or over 4 KiB. Check your
+     * own password rules before calling it.
+     */
+    async reset(token, password, { signIn = false } = {}) {
+        const { handler } = this.feature();
+        if (typeof token !== 'string' || !TOKEN_PATTERN.test(token) || !isHashablePassword(password)) {
+            return null;
+        }
+        const record = await this.storage.emailTokens.consumeEmailToken(sha256(token), 'password-reset');
+        if (!record || hasExpired(record.expiresAt, this.now())) {
+            return null;
+        }
+        const found = await handler.findUser(normalizeEmail(record.email));
+        const account = found && checked(found);
+        if (!account ||
+            account.id !== record.userId ||
+            account.email !== record.email ||
+            !safeEqual(fingerprint(account.passwordHash), record.fingerprint ?? '')) {
+            return null;
+        }
+        const passwordHash = await this.hasher.hash(password);
+        // Sign-ins end before the new password is stored, so a store that fails leaves the old password
+        // without its sessions rather than the new one next to them; and again after, for any sign-in
+        // that started in between.
+        await this.revokeSignIns(account.id);
+        await handler.updatePassword(account.id, passwordHash);
+        await this.storage.emailTokens.deleteUserEmailTokens(account.id, 'password-reset');
+        await this.revokeSignIns(account.id);
+        // The link reached the address, and the password is the owner's now.
+        await this.registry.handler('emailVerification')?.markVerified(account.id, account.email);
+        this.events.emit({ type: 'password-reset', userId: account.id });
+        const signedIn = signIn ? await this.signInService.signIn(account.id, { method: 'password-reset' }) : undefined;
+        return { userId: account.id, ...(signedIn && { signedIn }) };
+    }
+    async onModuleDestroy() {
+        await Promise.all(this.inFlight);
+    }
+    async issue(requested) {
+        const { options, handler } = this.feature();
+        const found = await handler.findUser(requested);
+        if (!found) {
+            this.events.emit({ type: 'password-reset-requested', email: requested });
+            return;
+        }
+        const account = checked(found);
+        const token = randomToken();
+        const now = this.now();
+        const expiresAt = new Date(now + this.ttl);
+        await this.storage.emailTokens.saveEmailToken({
+            id: sha256(token),
+            purpose: 'password-reset',
+            userId: account.id,
+            email: account.email,
+            fingerprint: fingerprint(account.passwordHash),
+            createdAt: new Date(now),
+            expiresAt,
+        });
+        this.events.emit({ type: 'password-reset-requested', email: requested, userId: account.id });
+        // To the address the account has stored, never to the one typed: a lookup that ignores accents
+        // or dots would otherwise mail `victim@example.com`'s link to whoever typed `victim@exämple.com`.
+        const url = new URL(options.url);
+        url.searchParams.set('token', token);
+        await handler.send({ userId: account.id, email: account.email, url: url.toString(), expiresAt });
+    }
+    /** Ends every session and refresh-token family of the user. */
+    async revokeSignIns(userId) {
+        await this.sessions.revokeAll(userId);
+        await this.tokens.revokeAll(userId);
+    }
+    /** The options and the handler; the module refuses to start with one and not the other. */
+    feature() {
+        const handler = this.registry.handler('passwordReset');
+        if (!this.options || !handler) {
+            throw new Error('PasswordResetService: password reset is not enabled. Configure `passwordReset` in the AuthenticationModule ' +
+                "options, and register a PasswordResetHandler: `registry.registerHandler('passwordReset', this)`.");
+        }
+        return { options: this.options, handler };
+    }
+    now() {
+        return this.options?.now?.() ?? Date.now();
+    }
+};
+PasswordResetService.logger = new Logger('PasswordResetService');
+PasswordResetService = PasswordResetService_1 = __decorate([
+    Injectable(),
+    __param(6, Optional()),
+    __param(6, Inject(AUTHENTICATION_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [AuthenticationStorage,
+        AuthenticationRegistry,
+        PasswordHasher,
+        SessionService,
+        TokenService,
+        SignInService, Object, AuthenticationEvents])
+], PasswordResetService);
+export { PasswordResetService };
+/**
+ * The account `findUser()` returned, with what a link is bound to: the
+ * address it goes to, and the password hash it replaces. A query that leaves
+ * either out would send links to the typed address, or keep them working
+ * after a password change.
+ */
+function checked(account) {
+    if (typeof account.email !== 'string' || account.email.trim() === '') {
+        throw new TypeError('PasswordResetHandler.findUser() must return the account’s stored `email`: the link goes there, never to the ' +
+            'address typed in the form.');
+    }
+    if (account.passwordHash === undefined) {
+        throw new TypeError('PasswordResetHandler.findUser() must return `passwordHash` (`null` for an account without a password): a link ' +
+            'works only while it is unchanged. Does the query leave the column out (TypeORM `select: false`)?');
+    }
+    return account;
+}
+/** What a reset link remembers of the password it replaces. */
+function fingerprint(passwordHash) {
+    return sha256(`nestjs-authentication password-reset v1 ${passwordHash ?? ''}`);
+}

package/dist/authentication.constants.d.ts

@@ -0,0 +1,13 @@
+/** The resolved module options: what `forRoot()` received, or what `forRootAsync()`'s factory returned. */
+export declare const AUTHENTICATION_MODULE_OPTIONS = "AUTHENTICATION_MODULE_OPTIONS";
+/** @internal The storage contracts the configured features use, for `AuthenticationStorage`'s production guard. */
+export declare const AUTHENTICATION_STORAGE_REQUIREMENTS: unique symbol;
+/** @internal Route metadata written by `@Public()` and `@Authenticate()`. */
+export declare const AUTHENTICATION_METADATA = "authentication:route";
+/**
+ * @internal The static brand on `AuthenticationGuard`, which subclasses
+ * inherit. `@nestjs/authorization` recognizes the guard by it, without
+ * importing this package or relying on the class name. A registry symbol,
+ * so every copy of either package agrees on it.
+ */
+export declare const AUTHENTICATION_GUARD_BRAND: unique symbol;

package/dist/authentication.constants.js

@@ -0,0 +1,13 @@
+/** The resolved module options: what `forRoot()` received, or what `forRootAsync()`'s factory returned. */
+export const AUTHENTICATION_MODULE_OPTIONS = 'AUTHENTICATION_MODULE_OPTIONS';
+/** @internal The storage contracts the configured features use, for `AuthenticationStorage`'s production guard. */
+export const AUTHENTICATION_STORAGE_REQUIREMENTS = Symbol('AUTHENTICATION_STORAGE_REQUIREMENTS');
+/** @internal Route metadata written by `@Public()` and `@Authenticate()`. */
+export const AUTHENTICATION_METADATA = 'authentication:route';
+/**
+ * @internal The static brand on `AuthenticationGuard`, which subclasses
+ * inherit. `@nestjs/authorization` recognizes the guard by it, without
+ * importing this package or relying on the class name. A registry symbol,
+ * so every copy of either package agrees on it.
+ */
+export const AUTHENTICATION_GUARD_BRAND = Symbol.for('@nestjs/authentication:guard');

package/dist/authentication.module-definition.d.ts

@@ -0,0 +1,21 @@
+import { type Provider } from '@nestjs/common';
+import type { AuthenticationModuleOptions, AuthenticationModuleExtras } from './interfaces/authentication-module-options.interface.js';
+export declare const ConfigurableModuleClass: import("@nestjs/common").ConfigurableModuleCls<AuthenticationModuleOptions, "forRoot", "createAuthenticationOptions", AuthenticationModuleExtras>, OPTIONS_TYPE: AuthenticationModuleOptions & Partial<AuthenticationModuleExtras>, ASYNC_OPTIONS_TYPE: import("@nestjs/common").ConfigurableModuleAsyncOptions<AuthenticationModuleOptions, "createAuthenticationOptions"> & Partial<AuthenticationModuleExtras>;
+/** What `forRootAsync()` takes: `useFactory`, `useClass` or `useExisting`, with `imports` and `inject` for them. */
+export type AuthenticationModuleAsyncOptions = typeof ASYNC_OPTIONS_TYPE;
+/** @internal The module options, once `startupChecks()` accepted them. */
+export declare const CHECKED_OPTIONS: unique symbol;
+/**
+ * @internal Runs once at startup: fails on options that don't exist (the
+ * classes that used to be options among them), then warns about lifetimes
+ * that look like seconds.
+ */
+export declare const startupChecks: Provider;
+/**
+ * @internal The storage contracts the configured features use, for the
+ * production guard: the features the options and the registered providers
+ * enable, and what each one reads or writes (`CONTRACTS_BY_FEATURE`, the one
+ * place that says so). Computed when storage locks, which locks the
+ * registry first: the credential providers decide whether sessions are used.
+ */
+export declare const storageRequirements: Provider;

package/dist/authentication.module-definition.js

@@ -0,0 +1,147 @@
+import { ConfigurableModuleBuilder, Logger } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
+import { AuthenticationGuard } from './guards/authentication.guard.js';
+import { AuthenticationRegistry, LOCK_REGISTRY } from './services/authentication-registry.service.js';
+import { contractsUsedBy, } from './storage/authentication.storage.js';
+import { AUTHENTICATION_MODULE_OPTIONS, AUTHENTICATION_STORAGE_REQUIREMENTS } from './authentication.constants.js';
+import { SessionCookieProvider } from './session/session-cookie.provider.js';
+export const { ConfigurableModuleClass, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE } = new ConfigurableModuleBuilder({ optionsInjectionToken: AUTHENTICATION_MODULE_OPTIONS })
+    .setClassMethodName('forRoot')
+    .setFactoryMethodName('createAuthenticationOptions')
+    .setExtras({ isGlobal: true, globalGuard: true }, (definition, extras) => ({
+    ...definition,
+    global: extras.isGlobal ?? true,
+    providers: [
+        ...(definition.providers ?? []),
+        ...(extras.globalGuard === false ? [] : [{ provide: APP_GUARD, useExisting: AuthenticationGuard }]),
+    ],
+}))
+    .build();
+/** @internal The module options, once `startupChecks()` accepted them. */
+export const CHECKED_OPTIONS = Symbol('AUTHENTICATION_CHECKED_OPTIONS');
+/**
+ * @internal Runs once at startup: fails on options that don't exist (the
+ * classes that used to be options among them), then warns about lifetimes
+ * that look like seconds.
+ */
+export const startupChecks = {
+    provide: CHECKED_OPTIONS,
+    inject: [AUTHENTICATION_MODULE_OPTIONS],
+    useFactory: (resolved) => {
+        const options = resolved ?? {};
+        checkKeys(options);
+        warnShortLifetimes(options, new Logger('AuthenticationModule'));
+        return options;
+    },
+};
+/**
+ * @internal The storage contracts the configured features use, for the
+ * production guard: the features the options and the registered providers
+ * enable, and what each one reads or writes (`CONTRACTS_BY_FEATURE`, the one
+ * place that says so). Computed when storage locks, which locks the
+ * registry first: the credential providers decide whether sessions are used.
+ */
+export const storageRequirements = {
+    provide: AUTHENTICATION_STORAGE_REQUIREMENTS,
+    inject: [CHECKED_OPTIONS, AuthenticationRegistry],
+    useFactory: (options, registry) => ({
+        get contracts() {
+            registry[LOCK_REGISTRY]();
+            const enabled = {
+                sessionCookie: registry.providers.some((provider) => provider instanceof SessionCookieProvider),
+                accessToken: options.accessToken !== undefined,
+                mfa: options.mfa !== undefined,
+                // With their handlers: the registry refuses one without the other.
+                magicLink: options.magicLink !== undefined,
+                oidc: options.oidc !== undefined,
+                passwordReset: options.passwordReset !== undefined,
+                emailVerification: options.emailVerification !== undefined,
+            };
+            return contractsUsedBy(Object.keys(enabled).filter((feature) => enabled[feature]));
+        },
+        allowInMemoryStorage: options.allowInMemoryStorage === true,
+    }),
+};
+const KNOWN_OPTIONS = new Set([
+    'session',
+    'password',
+    'mfa',
+    'magicLink',
+    'accessToken',
+    'refreshToken',
+    'oidc',
+    'passwordReset',
+    'emailVerification',
+    'allowInMemoryStorage',
+]);
+/** Where each class that used to be an option registers now. */
+const REGISTERED = {
+    providers: 'credential providers register themselves: provide the class in one of your modules, and call ' +
+        '`registry.registerProvider(this, { order })` from its constructor, with `registry: AuthenticationRegistry` injected',
+    magicLinkHandler: "handlers register themselves: `registry.registerHandler('magicLink', this)` from the handler's constructor",
+    oidcAccountResolver: "handlers register themselves: `registry.registerHandler('oidc', this)` from the resolver's constructor",
+    passwordResetHandler: "handlers register themselves: `registry.registerHandler('passwordReset', this)` from the handler's constructor",
+    emailVerificationHandler: "handlers register themselves: `registry.registerHandler('emailVerification', this)` from the handler's constructor",
+    oidcPath: 'the OIDC routes are your own controller now, calling OidcService; set `oidc.callbackUrl` to its callback URL',
+    imports: 'forRoot() takes values only; forRootAsync() takes `imports` for its factory',
+    stores: 'storage is registered by a provider: implement the store interfaces in an @Injectable() class and call ' +
+        '`storage.registerSource({ sessions: this, … })` from its constructor, with `storage: AuthenticationStorage` injected',
+};
+/**
+ * An option that doesn't exist fails at startup instead of being ignored: a
+ * class where registration belongs, a switch returned by a `forRootAsync()`
+ * factory (it goes at the top level, next to `useFactory`), or a typo.
+ */
+function checkKeys(options) {
+    for (const key of Object.keys(options)) {
+        if (KNOWN_OPTIONS.has(key)) {
+            continue;
+        }
+        if (key === 'isGlobal' || key === 'globalGuard') {
+            throw new Error(`AuthenticationModule: \`${key}\` is in the options the factory returned. It goes at the top level of ` +
+                'forRootAsync(), next to useFactory, because it decides what the module registers.');
+        }
+        const hint = REGISTERED[key];
+        throw new Error(`AuthenticationModule: \`${key}\` is not an option` +
+            (hint ? `: ${hint}.` : `. The options are ${[...KNOWN_OPTIONS].join(', ')}.`));
+    }
+}
+/** The lifetimes: what `@nestjs/jwt` and jsonwebtoken users are used to giving in seconds. */
+const LIFETIMES = [
+    ['accessToken.ttl', (options) => options.accessToken?.ttl],
+    ['refreshToken.ttl', (options) => options.refreshToken?.ttl],
+    ['refreshToken.absoluteTtl', (options) => options.refreshToken?.absoluteTtl],
+    ['session.absoluteTtl', (options) => options.session?.absoluteTtl],
+    ['session.idleTtl', (options) => options.session?.idleTtl],
+    ['mfa.pendingTtl', (options) => options.mfa?.pendingTtl],
+    ['magicLink.ttl', (options) => options.magicLink?.ttl],
+    ['oidc.transactionTtl', (options) => options.oidc?.transactionTtl],
+    ['passwordReset.ttl', (options) => options.passwordReset?.ttl],
+    ['emailVerification.ttl', (options) => options.emailVerification?.ttl],
+];
+/**
+ * A numeric lifetime is milliseconds, so `ttl: 3600` means 3.6 seconds,
+ * not the hour a `@nestjs/jwt` user meant. One warning per lifetime under a
+ * minute (`0`, which turns `session.idleTtl` off, excepted), suggesting the
+ * string that the number would mean in seconds.
+ */
+function warnShortLifetimes(options, logger) {
+    for (const [path, read] of LIFETIMES) {
+        const value = read(options);
+        if (typeof value !== 'number' || !(value > 0 && value < 60_000)) {
+            continue;
+        }
+        logger.warn(`\`${path}\` is ${value} milliseconds. Numeric lifetimes are milliseconds, not seconds as in ` +
+            `@nestjs/jwt: did you mean '${asSeconds(value)}'?`);
+    }
+}
+/** `value` read as seconds, in the largest whole unit: 900 is `15m`, 3600 is `1h`. */
+function asSeconds(value) {
+    if (value % 3_600 === 0) {
+        return `${value / 3_600}h`;
+    }
+    if (value % 60 === 0) {
+        return `${value / 60}m`;
+    }
+    return `${value}s`;
+}

package/dist/authentication.module.d.ts

@@ -0,0 +1,34 @@
+import { type DynamicModule, type OnModuleInit } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+import { ConfigurableModuleClass } from './authentication.module-definition.js';
+import type { AuthenticationModuleForRootOptions } from './interfaces/authentication-module-options.interface.js';
+import { AuthenticationRegistry } from './services/authentication-registry.service.js';
+import { AuthenticationStorage } from './storage/authentication.storage.js';
+/**
+ * `AuthenticationModule.forRoot({ session, mfa, … })`, or
+ * `forRootAsync({ inject, useFactory })` for values read from config. Global
+ * by default. Registers the authentication guard, the interceptor that opens
+ * `AuthenticationContext` around each handler, `AuthenticationRegistry`,
+ * where the app's credential providers and feature handlers register, and
+ * `AuthenticationStorage`, where its stores do.
+ *
+ * Global enhancers do not reach everywhere by default: a hybrid app's
+ * message handlers need `app.connectMicroservice(options, { inheritAppConfig:
+ * true })`, and GraphQL field resolvers `fieldResolverEnhancers: ['guards',
+ * 'interceptors']`, or the guard does not run there.
+ */
+export declare class AuthenticationModule extends ConfigurableModuleClass implements OnModuleInit {
+    private readonly registry;
+    private readonly storage;
+    private readonly moduleRef;
+    constructor(registry: AuthenticationRegistry, storage: AuthenticationStorage, moduleRef: ModuleRef);
+    static forRoot(options?: AuthenticationModuleForRootOptions): DynamicModule;
+    /**
+     * Locks both registries: every provider constructor (where providers,
+     * handlers and stores register) has run, and nothing has served a request
+     * yet. Fails on a feature missing its handler or its option, logs what
+     * registered, and fails in production on in-memory stores a configured
+     * feature relies on (see `allowInMemoryStorage`).
+     */
+    onModuleInit(): void;
+}

package/dist/authentication.module.js

@@ -0,0 +1,139 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Module } from '@nestjs/common';
+import { APP_INTERCEPTOR, ModuleRef } from '@nestjs/core';
+import { EmailVerificationService } from './account/email-verification.service.js';
+import { PasswordResetService } from './account/password-reset.service.js';
+import { ConfigurableModuleClass, startupChecks, storageRequirements, } from './authentication.module-definition.js';
+import { AuthenticationContext } from './context/authentication.context.js';
+import { AuthenticationScopeInterceptor } from './interceptors/authentication-scope.interceptor.js';
+import { AuthenticationScope } from './context/authentication-scope.service.js';
+import { AuthenticationRegistry, LOCK_REGISTRY } from './services/authentication-registry.service.js';
+import { AuthenticationStorage, LOCK_STORAGE } from './storage/authentication.storage.js';
+import { AuthenticationGuard } from './guards/authentication.guard.js';
+import { AUTHENTICATION_MODULE_OPTIONS } from './authentication.constants.js';
+import { AuthenticationEvents } from './events/authentication-events.service.js';
+import { WsAuthenticator } from './services/ws-authenticator.service.js';
+import { TokenService } from './jwt/token.service.js';
+import { MagicLinkService } from './magic-link/magic-link.service.js';
+import { MfaService } from './mfa/mfa.service.js';
+import { OidcService } from './oidc/oidc.service.js';
+import { PasswordHasher } from './services/password-hasher.service.js';
+import { SessionService } from './session/session.service.js';
+import { SignInService } from './session/sign-in.service.js';
+/**
+ * `AuthenticationModule.forRoot({ session, mfa, … })`, or
+ * `forRootAsync({ inject, useFactory })` for values read from config. Global
+ * by default. Registers the authentication guard, the interceptor that opens
+ * `AuthenticationContext` around each handler, `AuthenticationRegistry`,
+ * where the app's credential providers and feature handlers register, and
+ * `AuthenticationStorage`, where its stores do.
+ *
+ * Global enhancers do not reach everywhere by default: a hybrid app's
+ * message handlers need `app.connectMicroservice(options, { inheritAppConfig:
+ * true })`, and GraphQL field resolvers `fieldResolverEnhancers: ['guards',
+ * 'interceptors']`, or the guard does not run there.
+ */
+let AuthenticationModule = class AuthenticationModule extends ConfigurableModuleClass {
+    constructor(registry, storage, moduleRef) {
+        super();
+        this.registry = registry;
+        this.storage = storage;
+        this.moduleRef = moduleRef;
+    }
+    static forRoot(options = {}) {
+        return super.forRoot(options);
+    }
+    /**
+     * Locks both registries: every provider constructor (where providers,
+     * handlers and stores register) has run, and nothing has served a request
+     * yet. Fails on a feature missing its handler or its option, logs what
+     * registered, and fails in production on in-memory stores a configured
+     * feature relies on (see `allowInMemoryStorage`).
+     */
+    onModuleInit() {
+        this.registry[LOCK_REGISTRY]();
+        this.storage[LOCK_STORAGE]();
+        assertGraphqlContextPerRequest(this.moduleRef);
+    }
+};
+AuthenticationModule = __decorate([
+    Module({
+        providers: [
+            startupChecks,
+            storageRequirements,
+            AuthenticationRegistry,
+            AuthenticationStorage,
+            AuthenticationScope,
+            AuthenticationContext,
+            AuthenticationScopeInterceptor,
+            { provide: APP_INTERCEPTOR, useExisting: AuthenticationScopeInterceptor },
+            AuthenticationGuard,
+            AuthenticationEvents,
+            WsAuthenticator,
+            SessionService,
+            SignInService,
+            {
+                provide: PasswordHasher,
+                inject: [AUTHENTICATION_MODULE_OPTIONS],
+                useFactory: (options) => new PasswordHasher(options.password),
+            },
+            MfaService,
+            TokenService,
+            EmailVerificationService,
+            PasswordResetService,
+            MagicLinkService,
+            OidcService,
+        ],
+        exports: [
+            AUTHENTICATION_MODULE_OPTIONS,
+            AuthenticationRegistry,
+            AuthenticationStorage,
+            AuthenticationContext,
+            AuthenticationGuard,
+            AuthenticationEvents,
+            WsAuthenticator,
+            SessionService,
+            SignInService,
+            PasswordHasher,
+            MfaService,
+            TokenService,
+            EmailVerificationService,
+            PasswordResetService,
+            MagicLinkService,
+            OidcService,
+        ],
+    }),
+    __metadata("design:paramtypes", [AuthenticationRegistry,
+        AuthenticationStorage,
+        ModuleRef])
+], AuthenticationModule);
+export { AuthenticationModule };
+/**
+ * The guard authenticates a GraphQL operation from its context's `req`. A
+ * `context` given as an object is one object for every request, and
+ * `@nestjs/apollo` sets the first request as its `req` and keeps it: every
+ * later operation would be authenticated with the first caller's
+ * credentials. So such a configuration fails at startup.
+ */
+function assertGraphqlContextPerRequest(moduleRef) {
+    let options;
+    try {
+        options = moduleRef.get('GqlModuleOptions', { strict: false });
+    }
+    catch {
+        return; // no GraphQL module
+    }
+    if (typeof options?.context === 'object' && options.context !== null) {
+        throw new Error('AuthenticationModule: the GraphQL module’s `context` is an object, shared by every request: the first ' +
+            'request is kept as its `req`, and every later operation would be authenticated as that caller. Make it a ' +
+            'function that builds one per request: `context: ({ req, res }) => ({ req, res, ...yourValues })`.');
+    }
+}

package/dist/context/authentication-scope.service.d.ts

@@ -0,0 +1,39 @@
+import type { IncomingHttpHeaders } from 'node:http';
+import { type ExecutionContext } from '@nestjs/common';
+import type { AuthenticationResult } from '../interfaces/authentication-result.interface.js';
+export interface Scope {
+    result: AuthenticationResult<any, any> | null;
+    /** The call being handled; absent inside `AuthenticationContext.run()`. */
+    context?: ExecutionContext;
+}
+/** The request and response of an HTTP call, as the platform (Express, Fastify) provides them. */
+export interface HttpExchange {
+    request: {
+        headers: IncomingHttpHeaders;
+        method?: string;
+        ip?: string;
+    };
+    response?: unknown;
+}
+/** @internal Runs `fn` as the handling of this call (the interceptor, around `next.handle()`). */
+export declare function runCall<R>(scope: Scope, fn: () => R): R;
+/**
+ * @internal What the handler of this call sees: the result the guard recorded for it, when the
+ * interceptor is handling this handler (param decorators are resolved inside it).
+ */
+export declare function scopedResult(context: ExecutionContext): Scope['result'] | undefined;
+/**
+ * @internal The per-call scope behind `AuthenticationContext` and
+ * `SignInService`: its own `AsyncLocalStorage`, opened around each handler
+ * by `AuthenticationScopeInterceptor`.
+ */
+export declare class AuthenticationScope {
+    private readonly storage;
+    get current(): Scope | undefined;
+    run<R>(scope: Scope, fn: () => R): R;
+    /**
+     * The HTTP request and response of the current call: an HTTP handler, or
+     * a GraphQL resolver whose context carries `req` (and `res`).
+     */
+    exchange(): HttpExchange | undefined;
+}