@nestjs/authentication 0.0.1

package/dist/context/authentication-scope.service.js

@@ -0,0 +1,64 @@
+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 { AsyncLocalStorage } from 'node:async_hooks';
+import { Injectable } from '@nestjs/common';
+/**
+ * The call the interceptor is handling, for the param decorators, which have no instance to ask:
+ * one store for the process, entered with the instance's own by `AuthenticationScopeInterceptor`.
+ */
+const calls = new AsyncLocalStorage();
+/** @internal Runs `fn` as the handling of this call (the interceptor, around `next.handle()`). */
+export function runCall(scope, fn) {
+    return calls.run(scope, fn);
+}
+/**
+ * @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 function scopedResult(context) {
+    const call = calls.getStore();
+    return call?.context && call.context.getHandler() === context.getHandler() ? call.result : undefined;
+}
+/**
+ * @internal The per-call scope behind `AuthenticationContext` and
+ * `SignInService`: its own `AsyncLocalStorage`, opened around each handler
+ * by `AuthenticationScopeInterceptor`.
+ */
+let AuthenticationScope = class AuthenticationScope {
+    constructor() {
+        this.storage = new AsyncLocalStorage();
+    }
+    get current() {
+        return this.storage.getStore();
+    }
+    run(scope, fn) {
+        return this.storage.run(scope, fn);
+    }
+    /**
+     * The HTTP request and response of the current call: an HTTP handler, or
+     * a GraphQL resolver whose context carries `req` (and `res`).
+     */
+    exchange() {
+        const context = this.current?.context;
+        switch (context?.getType()) {
+            case 'http': {
+                const http = context.switchToHttp();
+                return { request: http.getRequest(), response: http.getResponse() };
+            }
+            case 'graphql': {
+                const gql = context.getArgByIndex(2);
+                return gql?.req ? { request: gql.req, response: gql.res } : undefined;
+            }
+            default:
+                return undefined;
+        }
+    }
+};
+AuthenticationScope = __decorate([
+    Injectable()
+], AuthenticationScope);
+export { AuthenticationScope };

package/dist/context/authentication.context.d.ts

@@ -0,0 +1,28 @@
+import type { AuthenticatedSession, AuthenticatedUser, AuthenticationResult } from '../interfaces/authentication-result.interface.js';
+import { AuthenticationScope } from './authentication-scope.service.js';
+/**
+ * The current user and session, readable from any singleton provider
+ * without passing the request down. Correct in the handler and in
+ * everything it calls or awaits, however many requests run at once. Empty
+ * in middleware, guards and exception filters, in interceptors that run
+ * before the module's own (an app's `APP_INTERCEPTOR` declared ahead of it:
+ * read `@CurrentUser()` or `request.user` there), and outside requests.
+ * A stream a handler returns but did not create (a shared `Subject`) runs
+ * its operators in the scope of whoever emits: read the user before
+ * building it.
+ */
+export declare class AuthenticationContext<TUser = AuthenticatedUser, TSession = AuthenticatedSession> {
+    private readonly scope;
+    constructor(scope?: AuthenticationScope);
+    /** The user, or `null` when anonymous or outside a request. */
+    get user(): TUser | null;
+    get session(): TSession | null;
+    get isAuthenticated(): boolean;
+    /**
+     * The user, or an {@link AuthenticationError}: a 401 on any transport when
+     * thrown under a handler, a plain error in a queue worker.
+     */
+    requireUser(): TUser;
+    /** Runs `fn` as `result.user`, for queue workers, cron jobs and tests. */
+    run<R>(result: AuthenticationResult<TUser, TSession> | null, fn: () => R): R;
+}

package/dist/context/authentication.context.js

@@ -0,0 +1,58 @@
+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 { Injectable } from '@nestjs/common';
+import { AuthenticationError } from '../errors/authentication.error.js';
+import { AuthenticationScope } from './authentication-scope.service.js';
+/**
+ * The current user and session, readable from any singleton provider
+ * without passing the request down. Correct in the handler and in
+ * everything it calls or awaits, however many requests run at once. Empty
+ * in middleware, guards and exception filters, in interceptors that run
+ * before the module's own (an app's `APP_INTERCEPTOR` declared ahead of it:
+ * read `@CurrentUser()` or `request.user` there), and outside requests.
+ * A stream a handler returns but did not create (a shared `Subject`) runs
+ * its operators in the scope of whoever emits: read the user before
+ * building it.
+ */
+let AuthenticationContext = class AuthenticationContext {
+    constructor(scope = new AuthenticationScope()) {
+        this.scope = scope;
+    }
+    /** The user, or `null` when anonymous or outside a request. */
+    get user() {
+        return this.scope.current?.result?.user ?? null;
+    }
+    get session() {
+        return this.scope.current?.result?.session ?? null;
+    }
+    get isAuthenticated() {
+        return !!this.scope.current?.result?.user;
+    }
+    /**
+     * The user, or an {@link AuthenticationError}: a 401 on any transport when
+     * thrown under a handler, a plain error in a queue worker.
+     */
+    requireUser() {
+        const user = this.user;
+        if (!user) {
+            throw new AuthenticationError();
+        }
+        return user;
+    }
+    /** Runs `fn` as `result.user`, for queue workers, cron jobs and tests. */
+    run(result, fn) {
+        return this.scope.run({ result }, fn);
+    }
+};
+AuthenticationContext = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [AuthenticationScope])
+], AuthenticationContext);
+export { AuthenticationContext };

package/dist/context/index.d.ts

@@ -0,0 +1,2 @@
+export * from './authentication-scope.service.js';
+export * from './authentication.context.js';

package/dist/context/index.js

@@ -0,0 +1,2 @@
+export * from './authentication-scope.service.js';
+export * from './authentication.context.js';

package/dist/decorators/authenticate.decorator.d.ts

@@ -0,0 +1,10 @@
+import type { AuthenticateOptions, RouteAuthentication } from '../interfaces/authenticate-options.interface.js';
+/** Merges into the metadata already on the class or method, so decorators can be stacked. */
+export declare function route(value: RouteAuthentication): ClassDecorator & MethodDecorator;
+/**
+ * Configures authentication for a controller or a handler. Every route
+ * already requires a signed-in user; use this to relax that (`optional`),
+ * tighten it (`mfa`, `verifiedEmail`, `providers`), or require it again under a `@Public()`
+ * class. Method options merge over class options, field by field.
+ */
+export declare const Authenticate: (options?: AuthenticateOptions) => ClassDecorator & MethodDecorator;

package/dist/decorators/authenticate.decorator.js

@@ -0,0 +1,18 @@
+import { AUTHENTICATION_METADATA } from '../authentication.constants.js';
+/** Merges into the metadata already on the class or method, so decorators can be stacked. */
+export function route(value) {
+    const defined = Object.fromEntries(Object.entries(value).filter(([, field]) => field !== undefined));
+    const decorator = (target, _key, descriptor) => {
+        const holder = descriptor ? descriptor.value : target;
+        const existing = Reflect.getMetadata(AUTHENTICATION_METADATA, holder);
+        Reflect.defineMetadata(AUTHENTICATION_METADATA, { ...existing, ...defined }, holder);
+    };
+    return decorator;
+}
+/**
+ * Configures authentication for a controller or a handler. Every route
+ * already requires a signed-in user; use this to relax that (`optional`),
+ * tighten it (`mfa`, `verifiedEmail`, `providers`), or require it again under a `@Public()`
+ * class. Method options merge over class options, field by field.
+ */
+export const Authenticate = (options = {}) => route({ ...options, public: false });

package/dist/decorators/current-session.decorator.d.ts

@@ -0,0 +1,2 @@
+/** The provider's session object (a `SessionRecord`, JWT claims, an `ApiKeySession`), or `null`. */
+export declare const CurrentSession: (...dataOrPipes: unknown[]) => ParameterDecorator;

package/dist/decorators/current-session.decorator.js

@@ -0,0 +1,6 @@
+import { createParamDecorator } from '@nestjs/common';
+import { resultOf } from '../utils/auth-state.util.js';
+/** The provider's session object (a `SessionRecord`, JWT claims, an `ApiKeySession`), or `null`. */
+export const CurrentSession = createParamDecorator((_, context) => {
+    return resultOf(context)?.session ?? null;
+});

package/dist/decorators/current-user.decorator.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The authenticated user, or `null` on `@Public()` and anonymous optional
+ * calls. `@CurrentUser('email')` picks one property; the key is checked
+ * against the `AuthenticationTypes` augmentation.
+ */
+export declare const CurrentUser: (...dataOrPipes: (string | import("@nestjs/common").ParameterDecoratorOptions | import("@nestjs/common").PipeTransform<any, any> | import("@nestjs/common").Type<import("@nestjs/common").PipeTransform<any, any>> | undefined)[]) => ParameterDecorator;

package/dist/decorators/current-user.decorator.js

@@ -0,0 +1,11 @@
+import { createParamDecorator } from '@nestjs/common';
+import { resultOf } from '../utils/auth-state.util.js';
+/**
+ * The authenticated user, or `null` on `@Public()` and anonymous optional
+ * calls. `@CurrentUser('email')` picks one property; the key is checked
+ * against the `AuthenticationTypes` augmentation.
+ */
+export const CurrentUser = createParamDecorator((key, context) => {
+    const user = resultOf(context)?.user ?? null;
+    return key && user ? user[key] : user;
+});

package/dist/decorators/index.d.ts

@@ -0,0 +1,4 @@
+export * from './authenticate.decorator.js';
+export * from './current-session.decorator.js';
+export * from './current-user.decorator.js';
+export * from './public.decorator.js';

package/dist/decorators/index.js

@@ -0,0 +1,4 @@
+export * from './authenticate.decorator.js';
+export * from './current-session.decorator.js';
+export * from './current-user.decorator.js';
+export * from './public.decorator.js';

package/dist/decorators/public.decorator.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Skips authentication: no provider runs, and `@CurrentUser()` is `null`.
+ * For health checks, the public catalog, and the routes that sign users in.
+ */
+export declare const Public: () => ClassDecorator & MethodDecorator;

package/dist/decorators/public.decorator.js

@@ -0,0 +1,6 @@
+import { route } from './authenticate.decorator.js';
+/**
+ * Skips authentication: no provider runs, and `@CurrentUser()` is `null`.
+ * For health checks, the public catalog, and the routes that sign users in.
+ */
+export const Public = () => route({ public: true });

package/dist/errors/authentication.error.d.ts

@@ -0,0 +1,27 @@
+import type { AuthenticationErrorOptions } from '../interfaces/authentication-error-options.interface.js';
+/**
+ * The base class of this package's errors, and on its own the error for
+ * credentials that are missing or failed verification: a 401 on every
+ * transport.
+ *
+ * - Thrown by a provider, the guard answers with it and sends `challenge`
+ *   as the `WWW-Authenticate` header.
+ * - Thrown by a handler or anything it calls (`requireUser()`, a failed
+ *   `TokenService.refresh()`), the module's interceptor turns it into the
+ *   transport's error for its `status`: an HTTP 401 (409 for
+ *   `MfaAlreadyEnrolledError`), GraphQL `UNAUTHENTICATED`, a `WsException`
+ *   or an `RpcException`.
+ * - Elsewhere (a queue worker), it is a plain `Error`.
+ */
+export declare class AuthenticationError extends Error {
+    /**
+     * 401, or 409 for `MfaAlreadyEnrolledError`: the caller's fault, not an
+     * outage, so other packages classify it without importing this class
+     * (`@nestjs/resilience` neither retries it nor counts it against a
+     * circuit breaker).
+     */
+    readonly status: 401 | 403 | 409;
+    readonly challenge?: string;
+    readonly code?: string;
+    constructor(message?: string, { challenge, code, cause }?: AuthenticationErrorOptions);
+}

package/dist/errors/authentication.error.js

@@ -0,0 +1,33 @@
+/**
+ * The base class of this package's errors, and on its own the error for
+ * credentials that are missing or failed verification: a 401 on every
+ * transport.
+ *
+ * - Thrown by a provider, the guard answers with it and sends `challenge`
+ *   as the `WWW-Authenticate` header.
+ * - Thrown by a handler or anything it calls (`requireUser()`, a failed
+ *   `TokenService.refresh()`), the module's interceptor turns it into the
+ *   transport's error for its `status`: an HTTP 401 (409 for
+ *   `MfaAlreadyEnrolledError`), GraphQL `UNAUTHENTICATED`, a `WsException`
+ *   or an `RpcException`.
+ * - Elsewhere (a queue worker), it is a plain `Error`.
+ */
+export class AuthenticationError extends Error {
+    constructor(message = 'Unauthorized', { challenge, code, cause } = {}) {
+        super(message, cause === undefined ? undefined : { cause });
+        /**
+         * 401, or 409 for `MfaAlreadyEnrolledError`: the caller's fault, not an
+         * outage, so other packages classify it without importing this class
+         * (`@nestjs/resilience` neither retries it nor counts it against a
+         * circuit breaker).
+         */
+        this.status = 401;
+        this.name = new.target.name;
+        if (challenge !== undefined) {
+            this.challenge = challenge;
+        }
+        if (code !== undefined) {
+            this.code = code;
+        }
+    }
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,7 @@
+export * from './authentication.error.js';
+export * from './jwt.error.js';
+export * from './magic-link.error.js';
+export * from './mfa-already-enrolled.error.js';
+export * from './oidc.error.js';
+export * from './refresh-token.error.js';
+export * from './secret-decryption.error.js';

package/dist/errors/index.js

@@ -0,0 +1,7 @@
+export * from './authentication.error.js';
+export * from './jwt.error.js';
+export * from './magic-link.error.js';
+export * from './mfa-already-enrolled.error.js';
+export * from './oidc.error.js';
+export * from './refresh-token.error.js';
+export * from './secret-decryption.error.js';

package/dist/errors/jwt.error.d.ts

@@ -0,0 +1,9 @@
+import { AuthenticationError } from './authentication.error.js';
+/**
+ * A token failed verification: malformed, badly signed, expired, for
+ * another issuer or audience. An {@link AuthenticationError} (401), so a
+ * route that lets one escape answers 401 on any transport.
+ */
+export declare class JwtError extends AuthenticationError {
+    constructor(message: string);
+}

package/dist/errors/jwt.error.js

@@ -0,0 +1,12 @@
+import { AuthenticationError } from './authentication.error.js';
+/**
+ * A token failed verification: malformed, badly signed, expired, for
+ * another issuer or audience. An {@link AuthenticationError} (401), so a
+ * route that lets one escape answers 401 on any transport.
+ */
+export class JwtError extends AuthenticationError {
+    constructor(message) {
+        super(message);
+        this.name = 'JwtError';
+    }
+}

package/dist/errors/magic-link.error.d.ts

@@ -0,0 +1,18 @@
+import { AuthenticationError } from './authentication.error.js';
+/**
+ * A link was presented in a browser other than the one that requested it
+ * (see `magicLink.bindToBrowser`). The one refusal `consume()` tells
+ * apart: the customer can act on it (open the link where they asked for
+ * it, or request a new one here), and it is decided before the link is
+ * looked up, so it reveals nothing about the token. Unknown, used, expired
+ * and refused links share one answer, `null`.
+ *
+ * An `AuthenticationError`: a route that lets it escape answers 401 on any
+ * transport, with `not_this_browser` as the body's `error`, the way
+ * `TokenService.issue()` answers `mfa_required`.
+ */
+export declare class MagicLinkError extends AuthenticationError {
+    /** Why the link was refused: the only reason apps are told. */
+    readonly reason: 'not-this-browser';
+    constructor();
+}

package/dist/errors/magic-link.error.js

@@ -0,0 +1,21 @@
+import { AuthenticationError } from './authentication.error.js';
+/**
+ * A link was presented in a browser other than the one that requested it
+ * (see `magicLink.bindToBrowser`). The one refusal `consume()` tells
+ * apart: the customer can act on it (open the link where they asked for
+ * it, or request a new one here), and it is decided before the link is
+ * looked up, so it reveals nothing about the token. Unknown, used, expired
+ * and refused links share one answer, `null`.
+ *
+ * An `AuthenticationError`: a route that lets it escape answers 401 on any
+ * transport, with `not_this_browser` as the body's `error`, the way
+ * `TokenService.issue()` answers `mfa_required`.
+ */
+export class MagicLinkError extends AuthenticationError {
+    constructor() {
+        super('Open the link in the browser you requested it from, or request a new one here', { code: 'not_this_browser' });
+        /** Why the link was refused: the only reason apps are told. */
+        this.reason = 'not-this-browser';
+        this.name = 'MagicLinkError';
+    }
+}

package/dist/errors/mfa-already-enrolled.error.d.ts

@@ -0,0 +1,14 @@
+import { AuthenticationError } from './authentication.error.js';
+/**
+ * Thrown by `MfaService.enroll()` when the user already has a confirmed
+ * authenticator and `replace` was not requested: overwriting it would turn
+ * the second factor off until the new one is confirmed. A route that lets
+ * it escape answers 409 on any transport. To replace an authenticator, call
+ * `enroll(…, { replace: true })` from a step-up route
+ * (`@Authenticate({ mfa: true })`), or `disable()` first.
+ */
+export declare class MfaAlreadyEnrolledError extends AuthenticationError {
+    readonly userId: string;
+    readonly status = 409;
+    constructor(userId: string);
+}

package/dist/errors/mfa-already-enrolled.error.js

@@ -0,0 +1,17 @@
+import { AuthenticationError } from './authentication.error.js';
+/**
+ * Thrown by `MfaService.enroll()` when the user already has a confirmed
+ * authenticator and `replace` was not requested: overwriting it would turn
+ * the second factor off until the new one is confirmed. A route that lets
+ * it escape answers 409 on any transport. To replace an authenticator, call
+ * `enroll(…, { replace: true })` from a step-up route
+ * (`@Authenticate({ mfa: true })`), or `disable()` first.
+ */
+export class MfaAlreadyEnrolledError extends AuthenticationError {
+    constructor(userId) {
+        super('Authenticator already enrolled');
+        this.userId = userId;
+        this.status = 409;
+        this.name = 'MfaAlreadyEnrolledError';
+    }
+}

package/dist/errors/oidc.error.d.ts

@@ -0,0 +1,15 @@
+export declare class OidcError extends Error {
+    /**
+     * `request`: bad or forged callback (400). `verification`: the IdP's
+     * answer failed checks (401). `unavailable`: the IdP is down or
+     * misconfigured (502), which is no fault of the user's.
+     */
+    readonly kind: 'request' | 'verification' | 'unavailable';
+    constructor(message: string, 
+    /**
+     * `request`: bad or forged callback (400). `verification`: the IdP's
+     * answer failed checks (401). `unavailable`: the IdP is down or
+     * misconfigured (502), which is no fault of the user's.
+     */
+    kind: 'request' | 'verification' | 'unavailable');
+}

package/dist/errors/oidc.error.js

@@ -0,0 +1,13 @@
+export class OidcError extends Error {
+    constructor(message, 
+    /**
+     * `request`: bad or forged callback (400). `verification`: the IdP's
+     * answer failed checks (401). `unavailable`: the IdP is down or
+     * misconfigured (502), which is no fault of the user's.
+     */
+    kind) {
+        super(message);
+        this.kind = kind;
+        this.name = 'OidcError';
+    }
+}

package/dist/errors/refresh-token.error.d.ts

@@ -0,0 +1,10 @@
+import type { RefreshTokenFailure } from '../interfaces/refresh-token-options.interface.js';
+import { AuthenticationError } from './authentication.error.js';
+/**
+ * A refresh token was refused. An {@link AuthenticationError}, so a route
+ * that lets it escape answers 401 on any transport.
+ */
+export declare class RefreshTokenError extends AuthenticationError {
+    readonly reason: RefreshTokenFailure;
+    constructor(reason: RefreshTokenFailure);
+}

package/dist/errors/refresh-token.error.js

@@ -0,0 +1,12 @@
+import { AuthenticationError } from './authentication.error.js';
+/**
+ * A refresh token was refused. An {@link AuthenticationError}, so a route
+ * that lets it escape answers 401 on any transport.
+ */
+export class RefreshTokenError extends AuthenticationError {
+    constructor(reason) {
+        super(`Refresh token ${reason}`);
+        this.reason = reason;
+        this.name = 'RefreshTokenError';
+    }
+}

package/dist/errors/secret-decryption.error.d.ts

@@ -0,0 +1,3 @@
+export declare class SecretDecryptionError extends Error {
+    constructor(message: string);
+}

package/dist/errors/secret-decryption.error.js

@@ -0,0 +1,6 @@
+export class SecretDecryptionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SecretDecryptionError';
+    }
+}

package/dist/events/authentication-events.interface.d.ts

@@ -0,0 +1,121 @@
+import type { MfaState } from '../interfaces/authentication-result.interface.js';
+/**
+ * A first factor signed a user in: a cookie session (`SignInService`), or a
+ * refresh-token family for a token client (`TokenService.issue()`).
+ */
+export interface AuthenticationSignInEvent {
+    type: 'sign-in';
+    userId: string;
+    /** The new cookie session. */
+    sessionId?: string;
+    /** The new refresh-token family. */
+    tokenFamilyId?: string;
+    /** How the user proved who they are, when the caller said: `password`, `magic-link`, `oidc:google`. */
+    method?: string;
+    /**
+     * `pending` while the session still needs its second factor; `verified`
+     * for tokens issued with one (`TokenService.issue()`).
+     */
+    mfa?: MfaState;
+    /** What the session stores next to the user (`session.metadata`). */
+    metadata?: Record<string, unknown>;
+}
+/** A TOTP or recovery code was accepted, at sign-in or for a token client. */
+export interface AuthenticationMfaVerifiedEvent {
+    type: 'mfa-verified';
+    userId: string;
+    method: 'totp' | 'recovery-code';
+}
+/** A code was refused. `locked` once the user reached `mfa.maxAttempts`. */
+export interface AuthenticationMfaFailedEvent {
+    type: 'mfa-failed';
+    userId: string;
+    method: 'totp' | 'recovery-code';
+    /** Failures within `mfa.lockoutWindow`, this one included. */
+    failures: number;
+    locked: boolean;
+}
+/** An authenticator was confirmed: a first one, or a replacement (`replaced`). */
+export interface AuthenticationMfaEnabledEvent {
+    type: 'mfa-enabled';
+    userId: string;
+    replaced: boolean;
+}
+/** The authenticator and the recovery codes were removed. */
+export interface AuthenticationMfaDisabledEvent {
+    type: 'mfa-disabled';
+    userId: string;
+}
+/** A new batch of recovery codes replaced the previous one. */
+export interface AuthenticationRecoveryCodesGeneratedEvent {
+    type: 'recovery-codes-generated';
+    userId: string;
+    count: number;
+}
+/**
+ * A spent refresh token came back, so two parties hold it: the family was
+ * revoked. A signal of token theft.
+ */
+export interface AuthenticationRefreshTokenReusedEvent {
+    type: 'refresh-token-reused';
+    userId: string;
+    tokenFamilyId: string;
+}
+/**
+ * A session or a token client was signed out: one session
+ * (`SignInService.signOut()`, `SessionService.revoke()`), one refresh-token
+ * family (`TokenService.revoke()`), or all of them (`everywhere`,
+ * `SignInService.signOutEverywhere()`).
+ */
+export interface AuthenticationSignOutEvent {
+    type: 'sign-out';
+    userId: string;
+    sessionId?: string;
+    tokenFamilyId?: string;
+    /** Every session and refresh-token family of the user. */
+    everywhere?: true;
+}
+/**
+ * Someone asked for a password reset link. `userId` is missing when no
+ * account has the address: nothing was sent. Many of those from one
+ * source is someone probing which addresses are registered.
+ */
+export interface AuthenticationPasswordResetRequestedEvent {
+    type: 'password-reset-requested';
+    /** Trimmed and lowercased. */
+    email: string;
+    userId?: string;
+}
+/**
+ * A reset link set a new password. Every session and refresh-token family
+ * of the user was ended, and the address counts as verified.
+ */
+export interface AuthenticationPasswordResetEvent {
+    type: 'password-reset';
+    userId: string;
+}
+/** A verification link proved the user's address. */
+export interface AuthenticationEmailVerifiedEvent {
+    type: 'email-verified';
+    userId: string;
+    email: string;
+}
+/**
+ * A magic link came back and signed nobody in. `not-this-browser`: the
+ * browser holds no transaction cookie for this link (`MagicLinkService`
+ * sets one when the link is requested), so the link was opened somewhere
+ * else, on another device, or planted by whoever requested it (login CSRF);
+ * it stays usable where it was requested, and `consume()` threw a
+ * `MagicLinkError`. The others are its `null`: `unknown`: malformed, used,
+ * never issued, or presented with a cookie whose secret is not the link's.
+ * `expired`: past `magicLink.ttl`. `refused`:
+ * `MagicLinkHandler.resolveUser()` returned `null`, or an account whose
+ * stored address is not the one the link was sent to.
+ */
+export interface AuthenticationMagicLinkRefusedEvent {
+    type: 'magic-link-refused';
+    reason: 'not-this-browser' | 'unknown' | 'expired' | 'refused';
+    /** The address the link was sent to, once the link was looked up (`expired`, `refused`). */
+    email?: string;
+}
+export type AuthenticationEvent = AuthenticationSignInEvent | AuthenticationSignOutEvent | AuthenticationMfaVerifiedEvent | AuthenticationMfaFailedEvent | AuthenticationMfaEnabledEvent | AuthenticationMfaDisabledEvent | AuthenticationRecoveryCodesGeneratedEvent | AuthenticationRefreshTokenReusedEvent | AuthenticationPasswordResetRequestedEvent | AuthenticationPasswordResetEvent | AuthenticationEmailVerifiedEvent | AuthenticationMagicLinkRefusedEvent;

package/dist/events/authentication-events.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/events/authentication-events.service.d.ts

@@ -0,0 +1,19 @@
+import { type OnApplicationShutdown } from '@nestjs/common';
+import { type Observable } from 'rxjs';
+import type { AuthenticationEvent } from './authentication-events.interface.js';
+/**
+ * The audit trail of sign-ins, sign-outs, second-factor changes, password
+ * resets, email verifications and refused magic links. Each event is also
+ * published on its `node:diagnostics_channel` channel
+ * (`nestjs:authentication:<type>`), for tooling that runs outside Nest.
+ * Listeners cannot change the outcome: a throwing channel subscriber is
+ * reported on the next tick, not in the sign-in that emitted.
+ */
+export declare class AuthenticationEvents implements OnApplicationShutdown {
+    private readonly subject;
+    /** Every event of this application, in order. */
+    readonly events$: Observable<AuthenticationEvent>;
+    /** @internal Called by the module's services. */
+    emit(event: AuthenticationEvent): void;
+    onApplicationShutdown(): void;
+}