@adonisjs/auth/build/modules/basic_auth_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 { BasicAuthGuardEvents, BasicAuthUserProviderContract } from './types.ts';
/**
 * BasicAuth guard implements the HTTP Authentication protocol
 *
 * @template UserProvider - The user provider contract
 *
 * @example
 * const guard = new BasicAuthGuard(
 *   'basic',
 *   ctx,
 *   emitter,
 *   userProvider
 * )
 *
 * const user = await guard.authenticate()
 * console.log('Authenticated user:', user.email)
 */
export declare class BasicAuthGuard<UserProvider extends BasicAuthUserProviderContract<unknown>> implements GuardContract<UserProvider[typeof PROVIDER_REAL_USER]> {
    #private;
    /**
     * Events emitted by the guard
     */
    [GUARD_KNOWN_EVENTS]: BasicAuthGuardEvents<UserProvider[typeof PROVIDER_REAL_USER]>;
    /**
     * Driver name of the guard
     */
    driverName: 'basic_auth';
    /**
     * Whether or not the authentication has been attempted
     * during the current request.
     */
    authenticationAttempted: boolean;
    /**
     * A boolean to know if the current request has
     * been authenticated
     */
    isAuthenticated: 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];
    /**
     * Creates a new BasicAuthGuard instance
     *
     * @param name - Unique name for the guard instance
     * @param ctx - HTTP context for the current request
     * @param emitter - Event emitter for guard events
     * @param userProvider - User provider for credential verification
     *
     * @example
     * const guard = new BasicAuthGuard(
     *   'basic',
     *   ctx,
     *   emitter,
     *   new BasicAuthLucidUserProvider()
     * )
     */
    constructor(name: string, ctx: HttpContext, emitter: EmitterLike<BasicAuthGuardEvents<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];
    /**
     * Authenticates the incoming HTTP request by looking for BasicAuth
     * credentials inside the request authorization header.
     *
     * @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 attempt to authenticate the user.
     *
     * The method returns a boolean indicating if the authentication
     * succeeded or failed.
     *
     * @example
     * const isAuthenticated = await guard.check()
     * if (isAuthenticated) {
     *   console.log('User is authenticated:', guard.user.email)
     * }
     */
    check(): Promise<boolean>;
    /**
     * Returns the Authorization header clients can use to authenticate
     * the request using basic auth.
     *
     * @param uid - The username or user identifier
     * @param password - The user's password
     *
     * @example
     * const clientAuth = await guard.authenticateAsClient('user@example.com', 'secret')
     * // Use clientAuth.headers.authorization in API tests
     */
    authenticateAsClient(uid: string, password: string): Promise<AuthClientResponse>;
}