@adonisjs/auth/build/src/authenticator.d.ts

Official authentication provider for Adonis framework

import type { HttpContext } from '@adonisjs/core/http';
import type { GuardFactory } from './types.ts';
/**
 * Authenticator is used to authenticate incoming HTTP requests
 * using one or more known guards.
 */
export declare class Authenticator<KnownGuards extends Record<string, GuardFactory>> {
    #private;
    /**
     * Name of the default guard configured in the auth configuration
     *
     * @example
     * const defaultGuard = auth.defaultGuard
     * console.log(defaultGuard) // 'web'
     */
    get defaultGuard(): keyof KnownGuards;
    /**
     * Reference to the guard using which the current
     * request has been authenticated. Returns undefined if
     * authentication has not been attempted or failed.
     *
     * @example
     * await auth.authenticate()
     * console.log(auth.authenticatedViaGuard) // 'web'
     */
    get authenticatedViaGuard(): keyof KnownGuards | undefined;
    /**
     * A boolean to know if the current request has been authenticated. The
     * property returns false when "authenticate" or "authenticateUsing"
     * methods are not used.
     *
     * @example
     * await auth.authenticate()
     * console.log(auth.isAuthenticated) // true
     */
    get isAuthenticated(): boolean;
    /**
     * Reference to the currently authenticated user. The property returns
     * undefined when "authenticate" or "authenticateUsing" methods are
     * not used.
     *
     * @example
     * await auth.authenticate()
     * console.log(auth.user?.email)
     */
    get user(): {
        [K in keyof KnownGuards]: ReturnType<KnownGuards[K]>['user'];
    }[keyof KnownGuards];
    /**
     * Whether or not the authentication has been attempted during
     * the current request. The property returns false when the
     * "authenticate" or "authenticateUsing" methods are not
     * used.
     *
     * @example
     * await auth.check()
     * console.log(auth.authenticationAttempted) // true
     */
    get authenticationAttempted(): boolean;
    /**
     * Creates a new Authenticator instance
     *
     * @param ctx - The HTTP context for the current request
     * @param config - Configuration object containing default guard and available guards
     *
     * @example
     * const authenticator = new Authenticator(ctx, {
     *   default: 'web',
     *   guards: { web: sessionGuard }
     * })
     */
    constructor(ctx: HttpContext, config: {
        default: keyof KnownGuards;
        guards: KnownGuards;
    });
    /**
     * Returns an instance of the logged-in user or throws an exception
     *
     * @throws {RuntimeException} When authentication has not been attempted
     *
     * @example
     * const user = auth.getUserOrFail()
     * console.log(user.id)
     */
    getUserOrFail(): {
        [K in keyof KnownGuards]: ReturnType<ReturnType<KnownGuards[K]>['getUserOrFail']>;
    }[keyof KnownGuards];
    /**
     * Returns an instance of a known guard. Guards instances are
     * cached during the lifecycle of an HTTP request.
     *
     * @param guard - Optional guard name. Uses default guard if not provided
     *
     * @example
     * const sessionGuard = auth.use('session')
     * const defaultGuard = auth.use()
     */
    use<Guard extends keyof KnownGuards>(guard?: Guard): ReturnType<KnownGuards[Guard]>;
    /**
     * Authenticate current request using the default guard. Calling this
     * method multiple times triggers multiple authentication with the
     * guard.
     *
     * @throws {E_UNAUTHORIZED_ACCESS} When authentication fails
     *
     * @example
     * const user = await auth.authenticate()
     * console.log('Authenticated user:', user.email)
     */
    authenticate(): Promise<{ [K in keyof KnownGuards]: ReturnType<ReturnType<KnownGuards[K]>["getUserOrFail"]>; }[keyof KnownGuards]>;
    /**
     * Silently attempt to authenticate the request using the default
     * guard. Calling this method multiple times triggers multiple
     * authentication with the guard.
     *
     * @example
     * const isAuthenticated = await auth.check()
     * if (isAuthenticated) {
     *   console.log('User is authenticated')
     * }
     */
    check(): Promise<boolean>;
    /**
     * Authenticate the request using all of the mentioned guards
     * or the default guard.
     *
     * The authentication process will stop after any of the mentioned
     * guards is able to authenticate the request successfully.
     *
     * Otherwise, "E_UNAUTHORIZED_ACCESS" will be raised.
     *
     * @param guards - Array of guard names to try for authentication
     * @param options - Options object with optional loginRoute for redirects
     *
     * @throws {E_UNAUTHORIZED_ACCESS} When none of the guards can authenticate
     *
     * @example
     * const user = await auth.authenticateUsing(['session', 'api'])
     * const userWithRedirect = await auth.authenticateUsing(['web'], { loginRoute: '/login' })
     */
    authenticateUsing(guards?: (keyof KnownGuards)[], options?: {
        loginRoute?: string;
    }): Promise<{
        [K in keyof KnownGuards]: ReturnType<ReturnType<KnownGuards[K]>['getUserOrFail']>;
    }[keyof KnownGuards]>;
    /**
     * Silently attempt to authenticate the request using all of the mentioned guards
     * or the default guard. Calling this method multiple times triggers multiple
     * authentication with the guard.
     *
     * @param guards - Array of guard names to check. Defaults to default guard
     *
     * @example
     * const isAuthenticated = await auth.checkUsing(['session', 'api'])
     * if (isAuthenticated) {
     *   const user = auth.user
     * }
     */
    checkUsing(guards?: (keyof KnownGuards)[]): Promise<boolean>;
}