@techelusive/nest-auth 0.0.0-stage → 0.2.1

package/dist/features/email-change/email-change.service.d.ts

@@ -0,0 +1,74 @@
+import { AuthOptions } from '../../auth-options.js';
+import { RateLimiterService } from '../../common/rate-limiter.service.js';
+import { RequestContext } from '../../common/request-context.js';
+import { LinkTokensService } from '../email-links/link-tokens.service.js';
+import { AuthEventsService } from '../events/auth-events.service.js';
+import { NotificationsService } from '../notifications/notifications.service.js';
+import { PasswordPolicyService } from '../passwords/password-policy.service.js';
+import { SettingsService } from '../settings/settings.service.js';
+import { UsersService } from '../users/users.service.js';
+/**
+ * Changing the email of an account:
+ * - POST /auth/email/change (signed in) checks it's really the owner (current password, or a
+ *   recent sign-in for accounts without one) and emails a confirmation link to the NEW address.
+ *   It answers the same whether or not that address already belongs to someone, so it can't be
+ *   used to find out who has an account.
+ * - POST /auth/email/change/confirm (the link) switches the email, marks it verified and tells
+ *   the OLD address, so an unwanted change gets noticed.
+ */
+export declare class EmailChangeService {
+    private readonly settingsService;
+    private readonly users;
+    private readonly linkTokens;
+    private readonly notifications;
+    private readonly passwordPolicy;
+    private readonly events;
+    private readonly rateLimiter;
+    private readonly database;
+    constructor(options: AuthOptions, settingsService: SettingsService, users: UsersService, linkTokens: LinkTokensService, notifications: NotificationsService, passwordPolicy: PasswordPolicyService, events: AuthEventsService, rateLimiter: RateLimiterService);
+    /**
+     * Starts an email change: checks it's really the owner and emails a confirmation link to the NEW address.
+     * Answers the same whether or not that address already belongs to someone.
+     * Only one change can be pending: a newer request cancels the older link.
+     *
+     * @param userId - The signed-in user.
+     * @param sessionId - This device's session (used for the "recent sign-in" check).
+     * @param typedNewEmail - The new email address.
+     * @param currentPassword - Required when the account has a password.
+     * @param request - Who is asking (for the audit log).
+     * @returns A generic success message.
+     * @throws AuthError EMAIL_UNCHANGED when the new email is the current one.
+     * @throws AuthError EMAIL_DOMAIN_NOT_ALLOWED when the domain is not in the allowed list.
+     * @throws AuthError INVALID_CREDENTIALS or RECENT_SIGN_IN_REQUIRED (see `confirmOwner`).
+     */
+    requestEmailChange(userId: string, sessionId: string, typedNewEmail: unknown, currentPassword: unknown, request: RequestContext): Promise<{
+        success: true;
+        message: "If this email can be used, a confirmation link is on its way to it.";
+    }>;
+    /**
+     * Finishes an email change (the emailed link): switches the email, marks it verified, cancels links sent to the old address,
+     * and tells the OLD address so an unwanted change gets noticed.
+     *
+     * @param token - The token from the confirmation link.
+     * @param request - Who is asking (for the audit log).
+     * @returns A success message and the updated profile.
+     * @throws AuthError INVALID_TOKEN when the link is unknown, used or expired.
+     * @throws AuthError EMAIL_IN_USE when someone took the address after the link was sent.
+     */
+    confirmEmailChange(token: unknown, request: RequestContext): Promise<{
+        success: true;
+        message: "Your email has been changed.";
+        user: import("../..").PublicUserProfile;
+    }>;
+    /**
+     * A stolen access token alone must not be enough to take over the account by changing its
+     * email. Accounts with a password must type it; others must have signed in in the last minutes.
+     *
+     * @param user - The signed-in user.
+     * @param sessionId - This device's session.
+     * @param currentPassword - What the user typed as their current password.
+     * @throws AuthError INVALID_CREDENTIALS when the password is wrong.
+     * @throws AuthError RECENT_SIGN_IN_REQUIRED when a password-less user signed in too long ago.
+     */
+    private confirmOwner;
+}

package/dist/features/email-change/email-change.service.js

@@ -0,0 +1,179 @@
+"use strict";
+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); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailChangeService = void 0;
+const common_1 = require("@nestjs/common");
+const typeorm_1 = require("typeorm");
+const auth_error_1 = require("../../common/auth-error.js");
+const identifiers_1 = require("../../common/identifiers.js");
+const rate_limiter_service_1 = require("../../common/rate-limiter.service.js");
+const constants_1 = require("../../constants.js");
+const entities_1 = require("../../database/entities/index.js");
+const link_tokens_service_1 = require("../email-links/link-tokens.service.js");
+const auth_events_service_1 = require("../events/auth-events.service.js");
+const notifications_service_1 = require("../notifications/notifications.service.js");
+const password_policy_service_1 = require("../passwords/password-policy.service.js");
+const settings_service_1 = require("../settings/settings.service.js");
+const users_service_1 = require("../users/users.service.js");
+/** Links sent to the old address stop working once the email changes. */
+const LINKS_FOR_THE_OLD_ADDRESS = [constants_1.LINK_PURPOSE.verifyEmail, constants_1.LINK_PURPOSE.resetPassword, constants_1.LINK_PURPOSE.magicSignIn];
+/**
+ * Changing the email of an account:
+ * - POST /auth/email/change (signed in) checks it's really the owner (current password, or a
+ *   recent sign-in for accounts without one) and emails a confirmation link to the NEW address.
+ *   It answers the same whether or not that address already belongs to someone, so it can't be
+ *   used to find out who has an account.
+ * - POST /auth/email/change/confirm (the link) switches the email, marks it verified and tells
+ *   the OLD address, so an unwanted change gets noticed.
+ */
+let EmailChangeService = class EmailChangeService {
+    settingsService;
+    users;
+    linkTokens;
+    notifications;
+    passwordPolicy;
+    events;
+    rateLimiter;
+    database;
+    constructor(options, settingsService, users, linkTokens, notifications, passwordPolicy, events, rateLimiter) {
+        this.settingsService = settingsService;
+        this.users = users;
+        this.linkTokens = linkTokens;
+        this.notifications = notifications;
+        this.passwordPolicy = passwordPolicy;
+        this.events = events;
+        this.rateLimiter = rateLimiter;
+        this.database = options.dataSource;
+    }
+    /**
+     * Starts an email change: checks it's really the owner and emails a confirmation link to the NEW address.
+     * Answers the same whether or not that address already belongs to someone.
+     * Only one change can be pending: a newer request cancels the older link.
+     *
+     * @param userId - The signed-in user.
+     * @param sessionId - This device's session (used for the "recent sign-in" check).
+     * @param typedNewEmail - The new email address.
+     * @param currentPassword - Required when the account has a password.
+     * @param request - Who is asking (for the audit log).
+     * @returns A generic success message.
+     * @throws AuthError EMAIL_UNCHANGED when the new email is the current one.
+     * @throws AuthError EMAIL_DOMAIN_NOT_ALLOWED when the domain is not in the allowed list.
+     * @throws AuthError INVALID_CREDENTIALS or RECENT_SIGN_IN_REQUIRED (see `confirmOwner`).
+     */
+    async requestEmailChange(userId, sessionId, typedNewEmail, currentPassword, request) {
+        const settings = await this.settingsService.getSettings();
+        await this.rateLimiter.consume(constants_1.RATE_LIMIT_KEY.changeEmailPerUser(userId), constants_1.RATE_LIMITS.changeEmailPerUser);
+        const user = await this.users.getUserOrThrow(userId);
+        const newEmail = (0, identifiers_1.normalizeEmail)(typedNewEmail);
+        if (newEmail === user.email)
+            throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.emailUnchanged);
+        if (!(0, identifiers_1.isEmailDomainAllowed)(newEmail, settings.registration.allowedEmailDomains))
+            throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.emailDomainNotAllowed);
+        await this.confirmOwner(user, sessionId, currentPassword);
+        // Only one change can be pending: a newer request cancels the older link.
+        await this.linkTokens.cancelLinkTokens(constants_1.LINK_PURPOSE.changeEmail, userId);
+        const addressIsFree = (await this.users.findUserByEmail(newEmail)) === null;
+        if (addressIsFree) {
+            const token = await this.linkTokens.createLinkToken(constants_1.LINK_PURPOSE.changeEmail, newEmail, userId);
+            await this.notifications.sendRequiredEmail({ type: constants_1.EMAIL_TYPE.confirmEmailChange, to: newEmail, token });
+        }
+        await this.events.record({
+            name: constants_1.AUTH_EVENTS.emailChangeRequested,
+            userId,
+            request,
+            details: { newEmail: (0, identifiers_1.maskEmail)(newEmail) },
+        });
+        return { success: true, message: constants_1.SUCCESS_MESSAGES.emailChangeRequested };
+    }
+    /**
+     * Finishes an email change (the emailed link): switches the email, marks it verified, cancels links sent to the old address,
+     * and tells the OLD address so an unwanted change gets noticed.
+     *
+     * @param token - The token from the confirmation link.
+     * @param request - Who is asking (for the audit log).
+     * @returns A success message and the updated profile.
+     * @throws AuthError INVALID_TOKEN when the link is unknown, used or expired.
+     * @throws AuthError EMAIL_IN_USE when someone took the address after the link was sent.
+     */
+    async confirmEmailChange(token, request) {
+        const settings = await this.settingsService.getSettings();
+        const { userId, email: newEmail } = await this.linkTokens.useLinkToken(token, constants_1.LINK_PURPOSE.changeEmail);
+        if (!userId)
+            throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.invalidOrExpiredLink);
+        const user = await this.users.getUserOrThrow(userId);
+        const previousEmail = user.email;
+        try {
+            await this.database.getRepository(entities_1.UserEntity).update({ id: userId }, { email: newEmail, isEmailVerified: true });
+        }
+        catch (error) {
+            // Someone else took the address between the request and the click.
+            if (error instanceof typeorm_1.QueryFailedError && error.code === constants_1.POSTGRES_UNIQUE_VIOLATION_CODE) {
+                throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.emailInUse);
+            }
+            throw error;
+        }
+        user.email = newEmail;
+        user.isEmailVerified = true;
+        for (const purpose of LINKS_FOR_THE_OLD_ADDRESS)
+            await this.linkTokens.cancelLinkTokens(purpose, userId);
+        if (previousEmail) {
+            await this.notifications.sendNoticeEmail({ type: constants_1.EMAIL_TYPE.emailChanged, to: previousEmail, newEmail: (0, identifiers_1.maskEmail)(newEmail) });
+        }
+        await this.events.record({
+            name: constants_1.AUTH_EVENTS.emailChanged,
+            userId,
+            request,
+            details: { previousEmail: previousEmail ? (0, identifiers_1.maskEmail)(previousEmail) : null, newEmail: (0, identifiers_1.maskEmail)(newEmail) },
+        });
+        // A pending account waiting only for a verified email becomes ACTIVE here.
+        const updatedUser = await this.users.activateIfReady(user, settings, request);
+        return { success: true, message: constants_1.SUCCESS_MESSAGES.emailChanged, user: this.users.toPublicProfile(updatedUser, settings) };
+    }
+    /**
+     * A stolen access token alone must not be enough to take over the account by changing its
+     * email. Accounts with a password must type it; others must have signed in in the last minutes.
+     *
+     * @param user - The signed-in user.
+     * @param sessionId - This device's session.
+     * @param currentPassword - What the user typed as their current password.
+     * @throws AuthError INVALID_CREDENTIALS when the password is wrong.
+     * @throws AuthError RECENT_SIGN_IN_REQUIRED when a password-less user signed in too long ago.
+     */
+    async confirmOwner(user, sessionId, currentPassword) {
+        const storedPassword = await this.database.getRepository(entities_1.PasswordEntity).findOne({ where: { userId: user.id } });
+        if (storedPassword) {
+            if (!(await this.passwordPolicy.verifyPassword(storedPassword.passwordHash, currentPassword))) {
+                throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.invalidCredentials);
+            }
+            return;
+        }
+        const session = await this.database.getRepository(entities_1.SessionEntity).findOne({ where: { id: sessionId, userId: user.id } });
+        const secondsSinceSignIn = session ? (Date.now() - session.createdAt.getTime()) / constants_1.SECOND_IN_MILLISECONDS : Infinity;
+        if (secondsSinceSignIn > constants_1.RECENT_SIGN_IN_SECONDS)
+            throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.recentSignInRequired);
+    }
+};
+exports.EmailChangeService = EmailChangeService;
+exports.EmailChangeService = EmailChangeService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(constants_1.AUTH_OPTIONS_TOKEN)),
+    __metadata("design:paramtypes", [Object, settings_service_1.SettingsService,
+        users_service_1.UsersService,
+        link_tokens_service_1.LinkTokensService,
+        notifications_service_1.NotificationsService,
+        password_policy_service_1.PasswordPolicyService,
+        auth_events_service_1.AuthEventsService,
+        rate_limiter_service_1.RateLimiterService])
+], EmailChangeService);
+//# sourceMappingURL=email-change.service.js.map

package/dist/features/email-change/email-change.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-change.service.js","sourceRoot":"","sources":["../../../src/features/email-change/email-change.service.ts"],"names":[],"mappings":"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"}

package/dist/features/email-links/email-verification.service.d.ts

@@ -0,0 +1,46 @@
+import { RateLimiterService } from '../../common/rate-limiter.service.js';
+import { RequestContext } from '../../common/request-context.js';
+import { NotificationsService } from '../notifications/notifications.service.js';
+import { SettingsService } from '../settings/settings.service.js';
+import { UsersService } from '../users/users.service.js';
+import { LinkTokensService } from './link-tokens.service';
+/**
+ * Proves the user owns their email address by sending them a link with a single-use token.
+ * Your app's page reads the token from the link and calls POST /auth/email/verify.
+ */
+export declare class EmailVerificationService {
+    private readonly settingsService;
+    private readonly users;
+    private readonly linkTokens;
+    private readonly notifications;
+    private readonly rateLimiter;
+    constructor(settingsService: SettingsService, users: UsersService, linkTokens: LinkTokensService, notifications: NotificationsService, rateLimiter: RateLimiterService);
+    /**
+     * Sends (or re-sends) the verification link. Answers the same whether or not the email has an account.
+     *
+     * @param typedEmail - The email from the request.
+     * @param request - Who is asking (for rate limits).
+     * @returns A generic success message.
+     * @throws AuthError TOO_MANY_REQUESTS after too many emails for this IP or address.
+     */
+    sendVerificationEmail(typedEmail: unknown, request: RequestContext): Promise<{
+        success: true;
+        message: "If this email needs verifying, a verification link is on its way.";
+    }>;
+    /**
+     * Uses the token from the link. If this was the last verification the settings require, the
+     * account becomes ACTIVE and the user can sign in.
+     *
+     * @param token - The token from the link.
+     * @param request - Who is asking (for the audit log).
+     * @returns The account's new status and anything still left to verify.
+     * @throws AuthError INVALID_TOKEN when the link is unknown, used, expired, or the account's
+     *   email has changed since it was sent.
+     */
+    verifyEmail(token: unknown, request: RequestContext): Promise<{
+        success: true;
+        message: "Your email has been verified.";
+        status: import("../../constants.js").AccountStatus;
+        pendingVerifications: import("../../constants.js").PendingVerification[];
+    }>;
+}

package/dist/features/email-links/email-verification.service.js

@@ -0,0 +1,94 @@
+"use strict";
+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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailVerificationService = void 0;
+const common_1 = require("@nestjs/common");
+const auth_error_1 = require("../../common/auth-error.js");
+const identifiers_1 = require("../../common/identifiers.js");
+const rate_limiter_service_1 = require("../../common/rate-limiter.service.js");
+const constants_1 = require("../../constants.js");
+const notifications_service_1 = require("../notifications/notifications.service.js");
+const settings_service_1 = require("../settings/settings.service.js");
+const users_service_1 = require("../users/users.service.js");
+const link_tokens_service_1 = require("./link-tokens.service");
+/**
+ * Proves the user owns their email address by sending them a link with a single-use token.
+ * Your app's page reads the token from the link and calls POST /auth/email/verify.
+ */
+let EmailVerificationService = class EmailVerificationService {
+    settingsService;
+    users;
+    linkTokens;
+    notifications;
+    rateLimiter;
+    constructor(settingsService, users, linkTokens, notifications, rateLimiter) {
+        this.settingsService = settingsService;
+        this.users = users;
+        this.linkTokens = linkTokens;
+        this.notifications = notifications;
+        this.rateLimiter = rateLimiter;
+    }
+    /**
+     * Sends (or re-sends) the verification link. Answers the same whether or not the email has an account.
+     *
+     * @param typedEmail - The email from the request.
+     * @param request - Who is asking (for rate limits).
+     * @returns A generic success message.
+     * @throws AuthError TOO_MANY_REQUESTS after too many emails for this IP or address.
+     */
+    async sendVerificationEmail(typedEmail, request) {
+        const email = (0, identifiers_1.normalizeEmail)(typedEmail);
+        await this.rateLimiter.consume(constants_1.RATE_LIMIT_KEY.sendEmailLinkPerIp(request.ipAddress), constants_1.RATE_LIMITS.sendEmailLinkPerIp);
+        await this.rateLimiter.consume(constants_1.RATE_LIMIT_KEY.sendEmailLinkPerEmail(email), constants_1.RATE_LIMITS.sendEmailLinkPerEmail);
+        const user = await this.users.findUserByEmail(email);
+        const needsVerifying = user && !user.isEmailVerified && user.status !== constants_1.ACCOUNT_STATUS.deleted && user.status !== constants_1.ACCOUNT_STATUS.suspended;
+        if (needsVerifying) {
+            const token = await this.linkTokens.createLinkToken(constants_1.LINK_PURPOSE.verifyEmail, email, user.id);
+            await this.notifications.sendRequiredEmail({ type: constants_1.EMAIL_TYPE.verifyEmail, to: email, token });
+        }
+        return { success: true, message: constants_1.SUCCESS_MESSAGES.verificationEmailSent };
+    }
+    /**
+     * Uses the token from the link. If this was the last verification the settings require, the
+     * account becomes ACTIVE and the user can sign in.
+     *
+     * @param token - The token from the link.
+     * @param request - Who is asking (for the audit log).
+     * @returns The account's new status and anything still left to verify.
+     * @throws AuthError INVALID_TOKEN when the link is unknown, used, expired, or the account's
+     *   email has changed since it was sent.
+     */
+    async verifyEmail(token, request) {
+        const settings = await this.settingsService.getSettings();
+        const usedToken = await this.linkTokens.useLinkToken(token, constants_1.LINK_PURPOSE.verifyEmail);
+        const user = usedToken.userId ? await this.users.findUserById(usedToken.userId) : null;
+        // The account's email may have changed after this link was sent; then the link proves nothing.
+        if (!user || user.email !== usedToken.email || user.status === constants_1.ACCOUNT_STATUS.deleted)
+            throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.invalidOrExpiredLink);
+        const verifiedUser = await this.users.markEmailVerified(user, settings, request);
+        return {
+            success: true,
+            message: constants_1.SUCCESS_MESSAGES.emailVerified,
+            status: verifiedUser.status,
+            pendingVerifications: this.users.getPendingVerifications(verifiedUser, settings),
+        };
+    }
+};
+exports.EmailVerificationService = EmailVerificationService;
+exports.EmailVerificationService = EmailVerificationService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [settings_service_1.SettingsService,
+        users_service_1.UsersService,
+        link_tokens_service_1.LinkTokensService,
+        notifications_service_1.NotificationsService,
+        rate_limiter_service_1.RateLimiterService])
+], EmailVerificationService);
+//# sourceMappingURL=email-verification.service.js.map

package/dist/features/email-links/email-verification.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-verification.service.js","sourceRoot":"","sources":["../../../src/features/email-links/email-verification.service.ts"],"names":[],"mappings":"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"}

package/dist/features/email-links/link-tokens.service.d.ts

@@ -0,0 +1,44 @@
+import { AuthOptions } from '../../auth-options.js';
+import { SettingsService } from '../settings/settings.service.js';
+import { LinkTokenPurpose } from '../../database/entities/index.js';
+/** A link token that was valid and has now been used up. */
+export interface UsedLinkToken {
+    userId: string | null;
+    email: string;
+}
+/**
+ * Single-use tokens put in emailed links (verify email, reset password, magic sign-in).
+ * Only the hash is stored. Creating a new token of a kind cancels the older ones for that email,
+ * so only the newest link in the user's inbox works.
+ */
+export declare class LinkTokensService {
+    private readonly settingsService;
+    private readonly database;
+    constructor(options: AuthOptions, settingsService: SettingsService);
+    /**
+     * Creates a single-use token for an emailed link. Older unused tokens of the same kind for this
+     * email stop working, so only the newest link in the inbox works.
+     *
+     * @param purpose - What the link is for (verify email, reset password, magic sign-in, change email).
+     * @param email - The address the link is sent to.
+     * @param userId - The account it belongs to, or null (e.g. a magic link before sign-up).
+     * @returns The plain token to put in the link. Only its hash is stored.
+     */
+    createLinkToken(purpose: LinkTokenPurpose, email: string, userId: string | null): Promise<string>;
+    /**
+     * Uses up a token. Done in one UPDATE so that two clicks at the same moment can't both succeed.
+     *
+     * @param token - The token from the link.
+     * @param purpose - What the link must be for.
+     * @returns The user id and email the token was created for.
+     * @throws AuthError INVALID_TOKEN for any problem (unknown, used, expired, wrong kind).
+     */
+    useLinkToken(token: unknown, purpose: LinkTokenPurpose): Promise<UsedLinkToken>;
+    /**
+     * Cancels every unused link of a kind for a user (e.g. reset links after the password changed).
+     *
+     * @param purpose - The kind of link.
+     * @param userId - The user.
+     */
+    cancelLinkTokens(purpose: LinkTokenPurpose, userId: string): Promise<void>;
+}

package/dist/features/email-links/link-tokens.service.js

@@ -0,0 +1,122 @@
+"use strict";
+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); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LinkTokensService = void 0;
+const common_1 = require("@nestjs/common");
+const typeorm_1 = require("typeorm");
+const auth_error_1 = require("../../common/auth-error.js");
+const random_secrets_1 = require("../../common/crypto/random-secrets.js");
+const constants_1 = require("../../constants.js");
+const settings_service_1 = require("../settings/settings.service.js");
+const entities_1 = require("../../database/entities/index.js");
+/**
+ * How long each kind of link works, from the settings.
+ *
+ * @param purpose - The kind of link.
+ * @param settings - The current settings.
+ * @returns The lifetime in seconds.
+ */
+function linkLifetimeSeconds(purpose, settings) {
+    switch (purpose) {
+        case constants_1.LINK_PURPOSE.verifyEmail:
+            return settings.emailVerification.linkExpiresInHours * constants_1.HOUR_IN_SECONDS;
+        case constants_1.LINK_PURPOSE.resetPassword:
+            return settings.passwordReset.linkExpiresInMinutes * constants_1.MINUTE_IN_SECONDS;
+        case constants_1.LINK_PURPOSE.magicSignIn:
+            return settings.magicLink.expiresInMinutes * constants_1.MINUTE_IN_SECONDS;
+        case constants_1.LINK_PURPOSE.changeEmail:
+            return settings.emailChange.linkExpiresInMinutes * constants_1.MINUTE_IN_SECONDS;
+    }
+}
+/**
+ * Single-use tokens put in emailed links (verify email, reset password, magic sign-in).
+ * Only the hash is stored. Creating a new token of a kind cancels the older ones for that email,
+ * so only the newest link in the user's inbox works.
+ */
+let LinkTokensService = class LinkTokensService {
+    settingsService;
+    database;
+    constructor(options, settingsService) {
+        this.settingsService = settingsService;
+        this.database = options.dataSource;
+    }
+    /**
+     * Creates a single-use token for an emailed link. Older unused tokens of the same kind for this
+     * email stop working, so only the newest link in the inbox works.
+     *
+     * @param purpose - What the link is for (verify email, reset password, magic sign-in, change email).
+     * @param email - The address the link is sent to.
+     * @param userId - The account it belongs to, or null (e.g. a magic link before sign-up).
+     * @returns The plain token to put in the link. Only its hash is stored.
+     */
+    async createLinkToken(purpose, email, userId) {
+        const { prefix } = constants_1.LINK_TOKEN_KINDS[purpose];
+        const lifetimeSeconds = linkLifetimeSeconds(purpose, await this.settingsService.getSettings());
+        const { plainToken, tokenHash } = (0, random_secrets_1.createRandomToken)(prefix);
+        await this.database.transaction(async (transaction) => {
+            await transaction.update(entities_1.LinkTokenEntity, { purpose, email, usedAt: (0, typeorm_1.IsNull)() }, { usedAt: new Date() });
+            await transaction.insert(entities_1.LinkTokenEntity, {
+                purpose,
+                email,
+                userId,
+                tokenHash,
+                expiresAt: new Date(Date.now() + lifetimeSeconds * constants_1.SECOND_IN_MILLISECONDS),
+            });
+        });
+        return plainToken;
+    }
+    /**
+     * Uses up a token. Done in one UPDATE so that two clicks at the same moment can't both succeed.
+     *
+     * @param token - The token from the link.
+     * @param purpose - What the link must be for.
+     * @returns The user id and email the token was created for.
+     * @throws AuthError INVALID_TOKEN for any problem (unknown, used, expired, wrong kind).
+     */
+    async useLinkToken(token, purpose) {
+        if (!(0, random_secrets_1.hasRandomTokenFormat)(token, constants_1.LINK_TOKEN_KINDS[purpose].prefix))
+            throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.invalidOrExpiredLink);
+        const result = await this.database
+            .createQueryBuilder()
+            .update(entities_1.LinkTokenEntity)
+            .set({ usedAt: () => 'now()' })
+            .where('token_hash = :tokenHash AND purpose = :purpose AND used_at IS NULL AND expires_at > now()', {
+            tokenHash: (0, random_secrets_1.sha256Hex)(token),
+            purpose,
+        })
+            // returning() takes entity property names; the raw rows use column names (user_id).
+            .returning(['userId', 'email'])
+            .execute();
+        const usedRow = result.raw[0];
+        if (!usedRow)
+            throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.invalidOrExpiredLink);
+        return { userId: usedRow.user_id, email: usedRow.email };
+    }
+    /**
+     * Cancels every unused link of a kind for a user (e.g. reset links after the password changed).
+     *
+     * @param purpose - The kind of link.
+     * @param userId - The user.
+     */
+    async cancelLinkTokens(purpose, userId) {
+        await this.database.getRepository(entities_1.LinkTokenEntity).update({ purpose, userId, usedAt: (0, typeorm_1.IsNull)() }, { usedAt: new Date() });
+    }
+};
+exports.LinkTokensService = LinkTokensService;
+exports.LinkTokensService = LinkTokensService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(constants_1.AUTH_OPTIONS_TOKEN)),
+    __metadata("design:paramtypes", [Object, settings_service_1.SettingsService])
+], LinkTokensService);
+//# sourceMappingURL=link-tokens.service.js.map

package/dist/features/email-links/link-tokens.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-tokens.service.js","sourceRoot":"","sources":["../../../src/features/email-links/link-tokens.service.ts"],"names":[],"mappings":"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"}

package/dist/features/events/auth-events.service.d.ts

@@ -0,0 +1,52 @@
+import { AuthOptions } from '../../auth-options.js';
+import { RequestContext } from '../../common/request-context.js';
+import { AuthEventName } from '../../constants.js';
+import type { JsonObject } from '../../database/entities/json-object.js';
+export interface RecordEventInput {
+    name: AuthEventName;
+    /** The user the event is about. */
+    userId: string | null;
+    /** Who did it when not the user themself: "admin:<id>", "system". */
+    performedBy?: string | null;
+    request?: RequestContext;
+    /** Extra facts. Never put passwords, tokens or codes here. */
+    details?: JsonObject;
+}
+/**
+ * The single place every auth event goes through. One call writes the audit log, then calls
+ * your `onEvent` handler, then queues a delivery for every webhook subscribed to the event.
+ *
+ * Recording an event never breaks the action that caused it: failures here are logged, not thrown.
+ */
+export declare class AuthEventsService {
+    private readonly options;
+    private readonly logger;
+    private readonly database;
+    constructor(options: AuthOptions);
+    /**
+     * Records an event: writes the audit log, calls your `onEvent` handler, and queues webhook deliveries.
+     * Never throws, so recording an event can't break the action that caused it.
+     *
+     * @param input - The event name, who it is about, who did it, the request, and extra details.
+     * @example
+     * await events.record({ name: AUTH_EVENTS.userSignedOut, userId, request, details: { sessionId } });
+     */
+    record(input: RecordEventInput): Promise<void>;
+    /**
+     * @param input - The event to write. Failures are logged, not thrown.
+     */
+    private writeAuditLog;
+    /**
+     * Calls AuthOptions.onEvent, if set. Failures in your handler are logged, not thrown.
+     *
+     * @param event - The event to pass on.
+     */
+    private callAppHandler;
+    /**
+     * Queues one delivery per enabled webhook that subscribes to this event. The worker sends them.
+     * Failures are logged, not thrown.
+     *
+     * @param event - The event to deliver.
+     */
+    private queueWebhookDeliveries;
+}