@adonisjs/auth/build/modules/session_guard/guard.d.ts

Official authentication provider for Adonis framework

import type { HttpContext } from '@adonisjs/core/http';
import type { EmitterLike } from '@adonisjs/core/types/events';
import type { AuthClientResponse, GuardContract } from '../../src/types.ts';
import { GUARD_KNOWN_EVENTS, type PROVIDER_REAL_USER } from '../../src/symbols.ts';
import type { SessionGuardEvents, SessionGuardOptions, SessionUserProviderContract, SessionWithTokensUserProviderContract } from './types.ts';
/**
 * Session guard uses AdonisJS session store to track logged-in
 * user information.
 *
 * @template UseRememberTokens - Whether the guard supports remember me tokens
 * @template UserProvider - The user provider contract
 *
 * @example
 * const guard = new SessionGuard(
 *   'web',
 *   ctx,
 *   { useRememberMeTokens: true },
 *   emitter,
 *   userProvider
 * )
 *
 * const user = await guard.authenticate()
 * console.log('Authenticated user:', user.email)
 */
export declare class SessionGuard<UseRememberTokens extends boolean, UserProvider extends UseRememberTokens extends true ? SessionWithTokensUserProviderContract<unknown> : SessionUserProviderContract<unknown>> implements GuardContract<UserProvider[typeof PROVIDER_REAL_USER]> {
    #private;
    /**
     * Events emitted by the guard
     */
    [GUARD_KNOWN_EVENTS]: SessionGuardEvents<UserProvider[typeof PROVIDER_REAL_USER]>;
    /**
     * Driver name of the guard
     */
    driverName: 'session';
    /**
     * Whether or not the authentication has been attempted
     * during the current request.
     */
    authenticationAttempted: boolean;
    /**
     * A boolean to know if a remember me token was used in attempt
     * to login a user.
     */
    attemptedViaRemember: boolean;
    /**
     * A boolean to know if the current request has
     * been authenticated
     */
    isAuthenticated: boolean;
    /**
     * A boolean to know if the current request is authenticated
     * using the "rememember_me" token.
     */
    viaRemember: boolean;
    /**
     * Find if the user has been logged out during
     * the current request
     */
    isLoggedOut: boolean;
    /**
     * Reference to an instance of the authenticated user.
     * The value only exists after calling one of the
     * following methods.
     *
     * - authenticate
     * - check
     *
     * You can use the "getUserOrFail" method to throw an exception if
     * the request is not authenticated.
     */
    user?: UserProvider[typeof PROVIDER_REAL_USER];
    /**
     * The key used to store the logged-in user id inside
     * session
     *
     * @example
     * console.log('Session key:', guard.sessionKeyName) // 'auth_web'
     */
    get sessionKeyName(): string;
    /**
     * The key used to store the remember me token cookie
     *
     * @example
     * console.log('Remember me key:', guard.rememberMeKeyName) // 'remember_web'
     */
    get rememberMeKeyName(): string;
    /**
     * Creates a new SessionGuard instance
     *
     * @param name - Unique name for the guard instance
     * @param ctx - HTTP context for the current request
     * @param options - Configuration options for the session guard
     * @param emitter - Event emitter for guard events
     * @param userProvider - User provider for authentication
     *
     * @example
     * const guard = new SessionGuard(
     *   'web',
     *   ctx,
     *   { useRememberMeTokens: true, rememberMeTokensAge: '30d' },
     *   emitter,
     *   userProvider
     * )
     */
    constructor(name: string, ctx: HttpContext, options: SessionGuardOptions<UseRememberTokens>, emitter: EmitterLike<SessionGuardEvents<UserProvider[typeof PROVIDER_REAL_USER]>>, userProvider: UserProvider);
    /**
     * Returns an instance of the authenticated user. Or throws
     * an exception if the request is not authenticated.
     *
     * @throws {E_UNAUTHORIZED_ACCESS} When user is not authenticated
     *
     * @example
     * const user = guard.getUserOrFail()
     * console.log('User:', user.email)
     */
    getUserOrFail(): UserProvider[typeof PROVIDER_REAL_USER];
    /**
     * Login user using sessions. Optionally, you can also create
     * a remember me token to automatically login user when their
     * session expires.
     *
     * @param user - The user to login
     * @param remember - Whether to create a remember me token
     *
     * @example
     * await guard.login(user, true)
     * console.log('User logged in with remember me token')
     */
    login(user: UserProvider[typeof PROVIDER_REAL_USER], remember?: boolean): Promise<void>;
    /**
     * Logout a user by removing its state from the session
     * store and delete the remember me cookie (if any).
     *
     * @example
     * await guard.logout()
     * console.log('User logged out successfully')
     */
    logout(): Promise<void>;
    /**
     * Authenticate the current HTTP request by verifying the session
     * or remember me token and fails with an exception if authentication fails
     *
     * @throws {E_UNAUTHORIZED_ACCESS} When authentication fails
     *
     * @example
     * try {
     *   const user = await guard.authenticate()
     *   console.log('Authenticated as:', user.email)
     * } catch (error) {
     *   console.log('Authentication failed')
     * }
     */
    authenticate(): Promise<UserProvider[typeof PROVIDER_REAL_USER]>;
    /**
     * Silently check if the user is authenticated or not, without
     * throwing any exceptions
     *
     * @example
     * const isAuthenticated = await guard.check()
     * if (isAuthenticated) {
     *   console.log('User is authenticated:', guard.user.email)
     * }
     */
    check(): Promise<boolean>;
    /**
     * Returns the session info for the clients to send during
     * an HTTP request to mark the user as logged-in.
     *
     * @param user - The user to authenticate as
     *
     * @example
     * const clientAuth = await guard.authenticateAsClient(user)
     * // Use clientAuth.session in API tests
     */
    authenticateAsClient(user: UserProvider[typeof PROVIDER_REAL_USER]): Promise<AuthClientResponse>;
}