@nestjs/authentication 0.0.1

package/LICENSE

@@ -0,0 +1,23 @@
+(The MIT License)
+
+Copyright (c) 2026 Kamil Mysliwiec
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

package/README.md

@@ -0,0 +1,50 @@
+<p align="center">
+  <a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo-small.svg" width="120" alt="Nest Logo" /></a>
+</p>
+
+[travis-image]: https://api.travis-ci.org/nestjs/nest.svg?branch=master
+[travis-url]: https://travis-ci.org/nestjs/nest
+[linux-image]: https://img.shields.io/travis/nestjs/nest/master.svg?label=linux
+[linux-url]: https://travis-ci.org/nestjs/nest
+
+  <p align="center">A progressive <a href="http://nodejs.org" target="blank">Node.js</a> framework for building efficient and scalable server-side applications.</p>
+    <p align="center">
+<a href="https://www.npmjs.com/~nestjscore"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
+<a href="https://www.npmjs.com/~nestjscore"><img src="https://img.shields.io/npm/l/@nestjs/core.svg" alt="Package License" /></a>
+<a href="https://www.npmjs.com/~nestjscore"><img src="https://img.shields.io/npm/dm/@nestjs/core.svg" alt="NPM Downloads" /></a>
+<a href="https://discord.gg/G7Qnnhy" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
+<a href="https://opencollective.com/nest#backer"><img src="https://opencollective.com/nest/backers/badge.svg" alt="Backers on Open Collective" /></a>
+<a href="https://opencollective.com/nest#sponsor"><img src="https://opencollective.com/nest/sponsors/badge.svg" alt="Sponsors on Open Collective" /></a>
+  <a href="https://paypal.me/kamilmysliwiec"><img src="https://img.shields.io/badge/Donate-PayPal-dc3d53.svg"/></a>
+  <a href="https://twitter.com/nestframework"><img src="https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow"></a>
+</p>
+  <!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)
+  [![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->
+
+## Description
+
+Authentication module for [Nest](https://github.com/nestjs/nest): a global guard with `@Public()` and `@Authenticate()`, credential providers as ordinary injectable classes (bearer JWT, cookie sessions, your own), server-side sessions with rotation, refresh tokens, TOTP second factor, magic links, OIDC sign-in, email verification and password reset, across HTTP, GraphQL, WebSockets and microservices, with no third-party dependencies.
+
+## Installation
+
+```bash
+$ npm i --save @nestjs/authentication
+```
+
+## Quick Start
+
+[Overview & Tutorial](https://docs.nestjs.com/security/authentication)
+
+## Support
+
+Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).
+
+## Stay in touch
+
+- Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec)
+- Website - [https://nestjs.com](https://nestjs.com/)
+- Twitter - [@nestframework](https://twitter.com/nestframework)
+
+## License
+
+Nest is [MIT licensed](LICENSE).

package/dist/account/email-verification.handler.d.ts

@@ -0,0 +1,23 @@
+import type { EmailVerificationLink } from '../interfaces/email-verification.interface.js';
+/**
+ * Implemented by the app: delivers verification links, and records a
+ * verified address in the app's users table (the module ships no mailer and
+ * never reads that table). An ordinary provider of one of your modules,
+ * which registers itself from its constructor:
+ * `registry.registerHandler('emailVerification', this)`.
+ */
+export declare abstract class EmailVerificationHandler {
+    abstract send(link: EmailVerificationLink): void | Promise<void>;
+    /**
+     * Marks the user's address verified, but only if it is still `email`
+     * (one conditional update: `UPDATE users SET email_verified = true WHERE
+     * id = ? AND email = ?`). Resolves `false` when the address changed since
+     * the link was sent, or the user is gone: the link then verifies nothing.
+     */
+    abstract markVerified(userId: string, email: string): boolean | Promise<boolean>;
+    /**
+     * Whether a signed-in user's current address is verified, for
+     * `@Authenticate({ verifiedEmail: true })`. Default: `user.emailVerified === true`.
+     */
+    isVerified(user: unknown): boolean | Promise<boolean>;
+}

package/dist/account/email-verification.handler.js

@@ -0,0 +1,17 @@
+import { hasVerifiedEmail } from './email.util.js';
+/**
+ * Implemented by the app: delivers verification links, and records a
+ * verified address in the app's users table (the module ships no mailer and
+ * never reads that table). An ordinary provider of one of your modules,
+ * which registers itself from its constructor:
+ * `registry.registerHandler('emailVerification', this)`.
+ */
+export class EmailVerificationHandler {
+    /**
+     * Whether a signed-in user's current address is verified, for
+     * `@Authenticate({ verifiedEmail: true })`. Default: `user.emailVerified === true`.
+     */
+    isVerified(user) {
+        return hasVerifiedEmail(user);
+    }
+}

package/dist/account/email-verification.service.d.ts

@@ -0,0 +1,46 @@
+import { AuthenticationRegistry } from '../services/authentication-registry.service.js';
+import { AuthenticationStorage } from '../storage/authentication.storage.js';
+import { AuthenticationEvents } from '../events/authentication-events.service.js';
+import type { EmailVerificationOptions } from '../interfaces/email-verification.interface.js';
+/**
+ * Email verification links: 256-bit single-use tokens, stored hashed, bound
+ * to the user and to the address they were sent to. Changing the address
+ * makes the links sent to the old one verify nothing.
+ *
+ * Point the link at a page that POSTs the token back: mail scanners and link
+ * previews follow GET links, and would use it up.
+ */
+export declare class EmailVerificationService {
+    private readonly storage;
+    private readonly registry;
+    private readonly events;
+    private readonly options?;
+    private readonly ttl;
+    constructor(storage: AuthenticationStorage, registry: AuthenticationRegistry, options?: {
+        emailVerification?: EmailVerificationOptions;
+    }, events?: AuthenticationEvents);
+    /**
+     * Sends a verification link for the user's current address, through
+     * `EmailVerificationHandler.send()`. Call it at sign-up, when the address
+     * changes, and when the user asks for a new link. The token is not returned.
+     */
+    send(user: {
+        id: string;
+        email: string;
+    }): Promise<{
+        expiresAt: Date;
+    }>;
+    /**
+     * Burns the token and asks `EmailVerificationHandler.markVerified()` to
+     * record the address, if it is still the user's. Resolves the verified
+     * address, or `null` for unknown, used or expired tokens and for an
+     * address the user has since changed.
+     */
+    verify(token: string): Promise<{
+        userId: string;
+        email: string;
+    } | null>;
+    /** The options and the handler; the module refuses to start with one and not the other. */
+    private feature;
+    private now;
+}

package/dist/account/email-verification.service.js

@@ -0,0 +1,111 @@
+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); }
+};
+import { Inject, Injectable, 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, 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';
+/**
+ * Email verification links: 256-bit single-use tokens, stored hashed, bound
+ * to the user and to the address they were sent to. Changing the address
+ * makes the links sent to the old one verify nothing.
+ *
+ * Point the link at a page that POSTs the token back: mail scanners and link
+ * previews follow GET links, and would use it up.
+ */
+let EmailVerificationService = class EmailVerificationService {
+    constructor(storage, registry, options, events = new AuthenticationEvents()) {
+        this.storage = storage;
+        this.registry = registry;
+        this.events = events;
+        this.options = options?.emailVerification;
+        if (this.options) {
+            requireUrlOption(this.options.url, 'emailVerification.url', 'the page that receives the link');
+        }
+        this.ttl = durationOr(this.options?.ttl, '24h');
+    }
+    /**
+     * Sends a verification link for the user's current address, through
+     * `EmailVerificationHandler.send()`. Call it at sign-up, when the address
+     * changes, and when the user asks for a new link. The token is not returned.
+     */
+    async send(user) {
+        const { options, handler } = this.feature();
+        // The address as the account has it: `markVerified()` compares it with the stored one, which
+        // may not be lowercase.
+        if (typeof user?.email !== 'string' || user.email.trim() === '') {
+            throw new TypeError('EmailVerificationService.send(): the user needs an `email` to send the link to.');
+        }
+        const email = user.email;
+        const token = randomToken();
+        const now = this.now();
+        const expiresAt = new Date(now + this.ttl);
+        await this.storage.emailTokens.saveEmailToken({
+            id: sha256(token),
+            purpose: 'email-verification',
+            userId: user.id,
+            email,
+            createdAt: new Date(now),
+            expiresAt,
+        });
+        const url = new URL(options.url);
+        url.searchParams.set('token', token);
+        await handler.send({ userId: user.id, email, url: url.toString(), expiresAt });
+        return { expiresAt };
+    }
+    /**
+     * Burns the token and asks `EmailVerificationHandler.markVerified()` to
+     * record the address, if it is still the user's. Resolves the verified
+     * address, or `null` for unknown, used or expired tokens and for an
+     * address the user has since changed.
+     */
+    async verify(token) {
+        const { handler } = this.feature();
+        if (typeof token !== 'string' || !TOKEN_PATTERN.test(token)) {
+            return null;
+        }
+        const record = await this.storage.emailTokens.consumeEmailToken(sha256(token), 'email-verification');
+        if (!record || hasExpired(record.expiresAt, this.now())) {
+            return null;
+        }
+        if (!(await handler.markVerified(record.userId, record.email))) {
+            return null;
+        }
+        await this.storage.emailTokens.deleteUserEmailTokens(record.userId, 'email-verification');
+        this.events.emit({ type: 'email-verified', userId: record.userId, email: record.email });
+        return { userId: record.userId, email: record.email };
+    }
+    /** The options and the handler; the module refuses to start with one and not the other. */
+    feature() {
+        const handler = this.registry.handler('emailVerification');
+        if (!this.options || !handler) {
+            throw new Error('EmailVerificationService: email verification is not enabled. Configure `emailVerification` in the ' +
+                "AuthenticationModule options, and register an EmailVerificationHandler: `registry.registerHandler('emailVerification', this)`.");
+        }
+        return { options: this.options, handler };
+    }
+    now() {
+        return this.options?.now?.() ?? Date.now();
+    }
+};
+EmailVerificationService = __decorate([
+    Injectable(),
+    __param(2, Optional()),
+    __param(2, Inject(AUTHENTICATION_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [AuthenticationStorage,
+        AuthenticationRegistry, Object, AuthenticationEvents])
+], EmailVerificationService);
+export { EmailVerificationService };

package/dist/account/email.util.d.ts

@@ -0,0 +1,14 @@
+/** @internal What `@Authenticate({ verifiedEmail: true })` checks without a handler. */
+export declare function hasVerifiedEmail(user: unknown): boolean;
+/**
+ * @internal The address as links carry it: trimmed, lowercased, and in
+ * Unicode NFC, so an address typed with a combining accent is the same
+ * address as the one stored precomposed.
+ */
+export declare function normalizeEmail(email: string): string;
+/**
+ * @internal An address worth mailing a link to: `local@domain`, at most 254
+ * characters (RFC 5321 §4.5.3.1.3), without whitespace or control
+ * characters, which a mailer could take for header syntax.
+ */
+export declare function isMailableEmail(normalized: string): boolean;

package/dist/account/email.util.js

@@ -0,0 +1,28 @@
+/** @internal What `@Authenticate({ verifiedEmail: true })` checks without a handler. */
+export function hasVerifiedEmail(user) {
+    return typeof user === 'object' && user !== null && user.emailVerified === true;
+}
+/**
+ * @internal The address as links carry it: trimmed, lowercased, and in
+ * Unicode NFC, so an address typed with a combining accent is the same
+ * address as the one stored precomposed.
+ */
+export function normalizeEmail(email) {
+    if (typeof email !== 'string') {
+        throw new TypeError('An email address must be a string');
+    }
+    return email.trim().normalize('NFC').toLowerCase();
+}
+/**
+ * @internal An address worth mailing a link to: `local@domain`, at most 254
+ * characters (RFC 5321 §4.5.3.1.3), without whitespace or control
+ * characters, which a mailer could take for header syntax.
+ */
+export function isMailableEmail(normalized) {
+    // oxlint-disable-next-line no-control-regex -- control characters are what it refuses
+    if (normalized.length > 254 || /[\s\x00-\x1f\x7f]/.test(normalized)) {
+        return false;
+    }
+    const at = normalized.lastIndexOf('@');
+    return at > 0 && at < normalized.length - 1;
+}

package/dist/account/in-memory-email-token.store.d.ts

@@ -0,0 +1,12 @@
+import type { EmailTokenPurpose, EmailTokenRecord, EmailTokenStore } from '../interfaces/email-token-store.interface.js';
+/**
+ * Process-local store: the default when no source is registered, and a
+ * test double. Drops expired tokens as new ones are saved, and holds at
+ * most 10,000, dropping the one that expires first.
+ */
+export declare class InMemoryEmailTokenStore implements EmailTokenStore {
+    private readonly tokens;
+    saveEmailToken(record: EmailTokenRecord): Promise<void>;
+    consumeEmailToken(id: string, purpose: EmailTokenPurpose): Promise<EmailTokenRecord | undefined>;
+    deleteUserEmailTokens(userId: string, purpose: EmailTokenPurpose): Promise<void>;
+}

package/dist/account/in-memory-email-token.store.js

@@ -0,0 +1,60 @@
+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;
+};
+import { Injectable } from '@nestjs/common';
+const MAX_PENDING = 10_000;
+/**
+ * Process-local store: the default when no source is registered, and a
+ * test double. Drops expired tokens as new ones are saved, and holds at
+ * most 10,000, dropping the one that expires first.
+ */
+let InMemoryEmailTokenStore = class InMemoryEmailTokenStore {
+    constructor() {
+        this.tokens = new Map();
+    }
+    async saveEmailToken(record) {
+        const now = record.createdAt.getTime();
+        // Insertion order is close to expiry order (one lifetime per purpose): stop at the first
+        // live entry; the cap bounds whatever that leaves behind.
+        for (const [id, token] of this.tokens) {
+            if (token.expiresAt.getTime() > now) {
+                break;
+            }
+            this.tokens.delete(id);
+        }
+        this.tokens.set(record.id, { ...record });
+        // Past the cap, the token that expires first goes, not the oldest: purposes have their own
+        // lifetimes, and a flood of one-hour reset links must not push out a day-long verification link.
+        if (this.tokens.size > MAX_PENDING) {
+            let first;
+            for (const token of this.tokens.values()) {
+                if (!first || token.expiresAt.getTime() < first.expiresAt.getTime()) {
+                    first = token;
+                }
+            }
+            this.tokens.delete(first.id);
+        }
+    }
+    async consumeEmailToken(id, purpose) {
+        const record = this.tokens.get(id);
+        if (record?.purpose !== purpose) {
+            return undefined;
+        }
+        this.tokens.delete(id);
+        return record;
+    }
+    async deleteUserEmailTokens(userId, purpose) {
+        for (const [id, token] of this.tokens) {
+            if (token.userId === userId && token.purpose === purpose) {
+                this.tokens.delete(id);
+            }
+        }
+    }
+};
+InMemoryEmailTokenStore = __decorate([
+    Injectable()
+], InMemoryEmailTokenStore);
+export { InMemoryEmailTokenStore };

package/dist/account/password-reset.handler.d.ts

@@ -0,0 +1,19 @@
+import type { PasswordResetAccount, PasswordResetLink } from '../interfaces/password-reset.interface.js';
+/**
+ * Implemented by the app: finds accounts by address, delivers reset links,
+ * and stores new password hashes (the module ships no mailer and never reads
+ * your users table). An ordinary provider of one of your modules, which
+ * registers itself from its constructor:
+ * `registry.registerHandler('passwordReset', this)`.
+ */
+export declare abstract class PasswordResetHandler {
+    /**
+     * The account whose address this is, with the address and the password
+     * hash it has stored, or `null`. Called with the address trimmed,
+     * lowercased and in Unicode NFC.
+     */
+    abstract findUser(email: string): PasswordResetAccount | null | Promise<PasswordResetAccount | null>;
+    abstract send(link: PasswordResetLink): void | Promise<void>;
+    /** Stores the new password's hash (from `PasswordHasher`). */
+    abstract updatePassword(userId: string, passwordHash: string): void | Promise<void>;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Implemented by the app: finds accounts by address, delivers reset links,
+ * and stores new password hashes (the module ships no mailer and never reads
+ * your users table). An ordinary provider of one of your modules, which
+ * registers itself from its constructor:
+ * `registry.registerHandler('passwordReset', this)`.
+ */
+export class PasswordResetHandler {
+}

package/dist/account/password-reset.service.d.ts

@@ -0,0 +1,69 @@
+import { type OnModuleDestroy } from '@nestjs/common';
+import { AuthenticationRegistry } from '../services/authentication-registry.service.js';
+import { AuthenticationStorage } from '../storage/authentication.storage.js';
+import { AuthenticationEvents } from '../events/authentication-events.service.js';
+import { TokenService } from '../jwt/token.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';
+import type { PasswordResetOptions, ResetPasswordOptions, PasswordResetResult } from '../interfaces/password-reset.interface.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.
+ */
+export declare class PasswordResetService implements OnModuleDestroy {
+    private readonly storage;
+    private readonly registry;
+    private readonly hasher;
+    private readonly sessions;
+    private readonly tokens;
+    private readonly signInService;
+    private readonly events;
+    private static readonly logger;
+    private readonly options?;
+    private readonly ttl;
+    private readonly inFlight;
+    constructor(storage: AuthenticationStorage, registry: AuthenticationRegistry, hasher: PasswordHasher, sessions: SessionService, tokens: TokenService, signInService: SignInService, options?: {
+        passwordReset?: PasswordResetOptions;
+    }, events?: AuthenticationEvents);
+    /**
+     * 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: string): void;
+    /**
+     * 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.
+     */
+    reset(token: string, password: string, { signIn }?: ResetPasswordOptions): Promise<PasswordResetResult | null>;
+    onModuleDestroy(): Promise<void>;
+    private issue;
+    /** Ends every session and refresh-token family of the user. */
+    private revokeSignIns;
+    /** The options and the handler; the module refuses to start with one and not the other. */
+    private feature;
+    private now;
+}