@adonisjs/auth 9.0.0-0 → 9.0.0-10

package/build/src/guards/basic_auth/guard.d.ts

@@ -0,0 +1,70 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { EmitterLike } from '@adonisjs/core/types/events';
+import type { BasicAuthGuardEvents } from './types.js';
+import type { GuardContract } from '../../auth/types.js';
+import type { UserProviderContract } from '../../core/types.js';
+import { PROVIDER_REAL_USER, GUARD_KNOWN_EVENTS } from '../../auth/symbols.js';
+/**
+ * Implementation of basic auth as an authentication guard
+ */
+export declare class BasicAuthGuard<UserProvider extends UserProviderContract<unknown>> implements GuardContract<UserProvider[typeof PROVIDER_REAL_USER]> {
+    #private;
+    [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 or logged-in
+     * user. The value only exists after calling one of the
+     * following methods.
+     *
+     * - authenticate
+     *
+     * You can use the "getUserOrFail" method to throw an exception if
+     * the request is not authenticated.
+     */
+    user?: UserProvider[typeof PROVIDER_REAL_USER];
+    constructor(name: string, ctx: HttpContext, userProvider: UserProvider);
+    /**
+     * Register an event emitter to listen for global events for
+     * authentication lifecycle.
+     */
+    setEmitter(emitter: EmitterLike<any>): this;
+    /**
+     * Returns an instance of the authenticated user. Or throws
+     * an exception if the request is not authenticated.
+     */
+    getUserOrFail(): UserProvider[typeof PROVIDER_REAL_USER];
+    /**
+     * Verifies user credentials and returns an instance of
+     * the user or throws "E_INVALID_BASIC_AUTH_CREDENTIALS" exception.
+     */
+    verifyCredentials(uid: string, password: string): Promise<UserProvider[typeof PROVIDER_REAL_USER]>;
+    /**
+     * Authenticates the current HTTP request for basic
+     * auth credentials
+     */
+    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.
+     */
+    check(): Promise<boolean>;
+    /**
+     * Not support
+     */
+    authenticateAsClient(_: UserProvider[typeof PROVIDER_REAL_USER]): Promise<never>;
+}

package/build/src/guards/basic_auth/guard.js

@@ -0,0 +1,193 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import auth from 'basic-auth';
+import { RuntimeException } from '@poppinss/utils';
+import debug from '../../auth/debug.js';
+import { AuthenticationException } from '../../auth/errors.js';
+import { GUARD_KNOWN_EVENTS } from '../../auth/symbols.js';
+/**
+ * Implementation of basic auth as an authentication guard
+ */
+export class BasicAuthGuard {
+    /**
+     * A unique name for the guard. It is used while
+     * emitting events
+     */
+    #name;
+    /**
+     * Reference to the current HTTP context
+     */
+    #ctx;
+    /**
+     * Provider to lookup user details
+     */
+    #userProvider;
+    /**
+     * Emitter to emit events
+     */
+    #emitter;
+    /**
+     * Driver name of the guard
+     */
+    driverName = 'basic_auth';
+    /**
+     * Whether or not the authentication has been attempted
+     * during the current request
+     */
+    authenticationAttempted = false;
+    /**
+     * A boolean to know if the current request has
+     * been authenticated
+     */
+    isAuthenticated = false;
+    /**
+     * Reference to an instance of the authenticated or logged-in
+     * user. The value only exists after calling one of the
+     * following methods.
+     *
+     * - authenticate
+     *
+     * You can use the "getUserOrFail" method to throw an exception if
+     * the request is not authenticated.
+     */
+    user;
+    constructor(name, ctx, userProvider) {
+        this.#ctx = ctx;
+        this.#name = name;
+        this.#userProvider = userProvider;
+    }
+    /**
+     * Notifies about authentication failure and throws the exception
+     */
+    #authenticationFailed(error) {
+        if (this.#emitter) {
+            this.#emitter.emit('basic_auth:authentication_failed', {
+                ctx: this.#ctx,
+                guardName: this.#name,
+                error,
+            });
+        }
+        throw error;
+    }
+    /**
+     * Register an event emitter to listen for global events for
+     * authentication lifecycle.
+     */
+    setEmitter(emitter) {
+        this.#emitter = emitter;
+        return this;
+    }
+    /**
+     * Returns an instance of the authenticated user. Or throws
+     * an exception if the request is not authenticated.
+     */
+    getUserOrFail() {
+        if (!this.user) {
+            throw AuthenticationException.E_INVALID_BASIC_AUTH_CREDENTIALS();
+        }
+        return this.user;
+    }
+    /**
+     * Verifies user credentials and returns an instance of
+     * the user or throws "E_INVALID_BASIC_AUTH_CREDENTIALS" exception.
+     */
+    async verifyCredentials(uid, password) {
+        debug('basic_auth_guard: attempting to verify credentials for uid "%s"', uid);
+        /**
+         * Attempt to find a user by the uid and raise
+         * error when unable to find one
+         */
+        const providerUser = await this.#userProvider.findByUid(uid);
+        if (!providerUser) {
+            this.#authenticationFailed(AuthenticationException.E_INVALID_BASIC_AUTH_CREDENTIALS());
+        }
+        /**
+         * Raise error when unable to verify password
+         */
+        const user = providerUser.getOriginal();
+        /**
+         * Raise error when unable to verify password
+         */
+        if (!(await providerUser.verifyPassword(password))) {
+            this.#authenticationFailed(AuthenticationException.E_INVALID_BASIC_AUTH_CREDENTIALS());
+        }
+        return user;
+    }
+    /**
+     * Authenticates the current HTTP request for basic
+     * auth credentials
+     */
+    async authenticate() {
+        /**
+         * Avoid re-authenticating when already authenticated
+         */
+        if (this.authenticationAttempted) {
+            return this.getUserOrFail();
+        }
+        /**
+         * Beginning authentication attempt
+         */
+        this.authenticationAttempted = true;
+        if (this.#emitter) {
+            this.#emitter.emit('basic_auth:authentication_attempted', {
+                ctx: this.#ctx,
+                guardName: this.#name,
+            });
+        }
+        /**
+         * Fetch credentials from the header
+         */
+        const credentials = auth(this.#ctx.request.request);
+        if (!credentials) {
+            this.#authenticationFailed(AuthenticationException.E_INVALID_BASIC_AUTH_CREDENTIALS());
+        }
+        debug('basic_auth_guard: authenticating user using credentials');
+        /**
+         * Verifying user credentials
+         */
+        this.user = await this.verifyCredentials(credentials.name, credentials.pass);
+        this.isAuthenticated = true;
+        debug('basic_auth_guard: marking user as authenticated');
+        if (this.#emitter) {
+            this.#emitter.emit('basic_auth:authentication_succeeded', {
+                ctx: this.#ctx,
+                guardName: this.#name,
+                user: this.user,
+            });
+        }
+        /**
+         * Return user
+         */
+        return this.getUserOrFail();
+    }
+    /**
+     * Silently attempt to authenticate the user.
+     *
+     * The method returns a boolean indicating if the authentication
+     * succeeded or failed.
+     */
+    async check() {
+        try {
+            await this.authenticate();
+            return true;
+        }
+        catch (error) {
+            if (error instanceof AuthenticationException) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Not support
+     */
+    async authenticateAsClient(_) {
+        throw new RuntimeException('Cannot authenticate as a client when using basic auth');
+    }
+}

package/build/src/guards/basic_auth/main.d.ts

@@ -0,0 +1,2 @@
+export { BasicAuthGuard } from './guard.js';
+export { basicAuthGuard } from './define_config.js';

package/build/{stubs → src/guards/basic_auth}/main.js

@@ -6,5 +6,5 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-import { getDirname } from '@poppinss/utils';
-export const stubsRoot = getDirname(import.meta.url);
+export { BasicAuthGuard } from './guard.js';
+export { basicAuthGuard } from './define_config.js';

package/build/src/guards/basic_auth/types.d.ts

@@ -0,0 +1,40 @@
+import { Exception } from '@poppinss/utils';
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * Events emitted by the basic auth guard
+ */
+export type BasicAuthGuardEvents<User> = {
+    /**
+     * The event is emitted when the user credentials
+     * have been verified successfully.
+     */
+    'basic_auth:credentials_verified': {
+        ctx: HttpContext;
+        guardName: string;
+        uid: string;
+        user: User;
+    };
+    /**
+     * Attempting to authenticate the user
+     */
+    'basic_auth:authentication_attempted': {
+        ctx: HttpContext;
+        guardName: string;
+    };
+    /**
+     * Authentication was successful
+     */
+    'basic_auth:authentication_succeeded': {
+        ctx: HttpContext;
+        guardName: string;
+        user: User;
+    };
+    /**
+     * Authentication failed
+     */
+    'basic_auth:authentication_failed': {
+        ctx: HttpContext;
+        guardName: string;
+        error: Exception;
+    };
+};

package/build/src/guards/basic_auth/types.js

@@ -0,0 +1,9 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+export {};

package/build/src/guards/session/define_config.js

@@ -37,7 +37,7 @@ export function sessionGuard(config) {
                 if (tokensProvider) {
                     guard.withRememberMeTokens(tokensProvider);
                 }
-                return guard.withEmitter(emitter);
+                return guard.setEmitter(emitter);
             };
         },
     };

package/build/src/guards/session/guard.d.ts

@@ -1,5 +1,5 @@
-import { Emitter } from '@adonisjs/core/events';
 import type { HttpContext } from '@adonisjs/core/http';
+import type { EmitterLike } from '@adonisjs/core/types/events';
 import type { GuardContract } from '../../auth/types.js';
 import { GUARD_KNOWN_EVENTS, PROVIDER_REAL_USER } from '../../auth/symbols.js';
 import type { SessionGuardEvents, SessionGuardConfig, RememberMeProviderContract, SessionUserProviderContract } from './types.js';
@@ -10,6 +10,10 @@ import type { SessionGuardEvents, SessionGuardConfig, RememberMeProviderContract
 export declare class SessionGuard<UserProvider extends SessionUserProviderContract<unknown>> implements GuardContract<UserProvider[typeof PROVIDER_REAL_USER]> {
     #private;
     [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
@@ -67,12 +71,28 @@ export declare class SessionGuard<UserProvider extends SessionUserProviderContra
      * Register an event emitter to listen for global events for
      * authentication lifecycle.
      */
-    withEmitter(emitter: Emitter<any>): this;
+    setEmitter(emitter: EmitterLike<any>): this;
     /**
      * Returns an instance of the authenticated user. Or throws
      * an exception if the request is not authenticated.
      */
     getUserOrFail(): UserProvider[typeof PROVIDER_REAL_USER];
+    /**
+     * Verifies user credentials and returns an instance of
+     * the user or throws "E_INVALID_CREDENTIALS" exception.
+     */
+    verifyCredentials(uid: string, password: string): Promise<UserProvider[typeof PROVIDER_REAL_USER]>;
+    /**
+     * Attempt to login a user after verifying their
+     * credentials.
+     */
+    attempt(uid: string, password: string, remember?: boolean): Promise<UserProvider[typeof PROVIDER_REAL_USER]>;
+    /**
+     * Attempt to login a user using the user id. The
+     * user will be first fetched from the db before
+     * marking them as logged-in
+     */
+    loginViaId(id: string | number, remember?: boolean): Promise<UserProvider[typeof PROVIDER_REAL_USER]>;
     /**
      * Login a user using the user object.
      */
@@ -89,4 +109,15 @@ export declare class SessionGuard<UserProvider extends SessionUserProviderContra
      * succeeded or failed.
      */
     check(): Promise<boolean>;
+    /**
+     * Logout user and revoke remember me token (if any)
+     */
+    logout(): Promise<void>;
+    /**
+     * Returns the session state for the user to be
+     * logged-in as a client
+     */
+    authenticateAsClient(user: UserProvider[typeof PROVIDER_REAL_USER]): Promise<{
+        session: Record<string, string | number>;
+    }>;
 }

package/build/src/guards/session/guard.js

@@ -9,8 +9,8 @@
 import { RuntimeException } from '@poppinss/utils';
 import debug from '../../auth/debug.js';
 import { RememberMeToken } from './token.js';
-import * as errors from '../../auth/errors.js';
 import { GUARD_KNOWN_EVENTS } from '../../auth/symbols.js';
+import { AuthenticationException, InvalidCredentialsException } from '../../auth/errors.js';
 /**
  * Session guard uses sessions and cookies to login and authenticate
  * users.
@@ -42,6 +42,10 @@ export class SessionGuard {
      * Emitter to emit events
      */
     #emitter;
+    /**
+     * Driver name of the guard
+     */
+    driverName = 'session';
     /**
      * Whether or not the authentication has been attempted
      * during the current request
@@ -116,17 +120,33 @@ export class SessionGuard {
         return this.#ctx.session;
     }
     /**
-     * Notifies about authenticatin failure and throws the exception
+     * Notifies about authentication failure and throws the exception
      */
     #authenticationFailed(error, sessionId) {
         if (this.#emitter) {
             this.#emitter.emit('session_auth:authentication_failed', {
+                ctx: this.#ctx,
+                guardName: this.#name,
                 error,
                 sessionId: sessionId,
             });
         }
         throw error;
     }
+    /**
+     * Notifies about login failure and throws the exception
+     */
+    #loginFailed(error, user) {
+        if (this.#emitter) {
+            this.#emitter.emit('session_auth:login_failed', {
+                ctx: this.#ctx,
+                guardName: this.#name,
+                error,
+                user,
+            });
+        }
+        throw error;
+    }
     /**
      * Register the remember me tokens provider to create
      * remember me tokens during user login.
@@ -143,7 +163,7 @@ export class SessionGuard {
      * Register an event emitter to listen for global events for
      * authentication lifecycle.
      */
-    withEmitter(emitter) {
+    setEmitter(emitter) {
         this.#emitter = emitter;
         return this;
     }
@@ -153,16 +173,78 @@ export class SessionGuard {
      */
     getUserOrFail() {
         if (!this.user) {
-            throw new errors.E_INVALID_AUTH_SESSION();
+            throw AuthenticationException.E_INVALID_AUTH_SESSION();
         }
         return this.user;
     }
+    /**
+     * Verifies user credentials and returns an instance of
+     * the user or throws "E_INVALID_CREDENTIALS" exception.
+     */
+    async verifyCredentials(uid, password) {
+        debug('session_guard: attempting to verify credentials for uid "%s"', uid);
+        /**
+         * Attempt to find a user by the uid and raise
+         * error when unable to find one
+         */
+        const providerUser = await this.#userProvider.findByUid(uid);
+        if (!providerUser) {
+            this.#loginFailed(InvalidCredentialsException.E_INVALID_CREDENTIALS(this.driverName), null);
+        }
+        /**
+         * Raise error when unable to verify password
+         */
+        const user = providerUser.getOriginal();
+        /**
+         * Raise error when unable to verify password
+         */
+        if (!(await providerUser.verifyPassword(password))) {
+            this.#loginFailed(InvalidCredentialsException.E_INVALID_CREDENTIALS(this.driverName), user);
+        }
+        /**
+         * Notify credentials have been verified
+         */
+        if (this.#emitter) {
+            this.#emitter.emit('session_auth:credentials_verified', {
+                ctx: this.#ctx,
+                guardName: this.#name,
+                uid,
+                user,
+            });
+        }
+        return user;
+    }
+    /**
+     * Attempt to login a user after verifying their
+     * credentials.
+     */
+    async attempt(uid, password, remember) {
+        const user = await this.verifyCredentials(uid, password);
+        return this.login(user, remember);
+    }
+    /**
+     * Attempt to login a user using the user id. The
+     * user will be first fetched from the db before
+     * marking them as logged-in
+     */
+    async loginViaId(id, remember) {
+        debug('session_guard: attempting to login user via id "%s"', id);
+        const providerUser = await this.#userProvider.findById(id);
+        if (!providerUser) {
+            this.#loginFailed(InvalidCredentialsException.E_INVALID_CREDENTIALS(this.driverName), null);
+        }
+        return this.login(providerUser.getOriginal(), remember);
+    }
     /**
      * Login a user using the user object.
      */
     async login(user, remember = false) {
         if (this.#emitter) {
-            this.#emitter.emit('session_auth:login_attempted', { user });
+            this.#emitter.emit('session_auth:login_attempted', {
+                ctx: this.#ctx,
+                user,
+                guardName: this.#name,
+            });
         }
         const providerUser = await this.#userProvider.createUserForGuard(user);
         const session = this.#getSession();
@@ -209,6 +291,8 @@ export class SessionGuard {
          */
         if (this.#emitter) {
             this.#emitter.emit('session_auth:login_succeeded', {
+                ctx: this.#ctx,
+                guardName: this.#name,
                 user,
                 sessionId: session.sessionId,
                 rememberMeToken: token,
@@ -231,6 +315,8 @@ export class SessionGuard {
          */
         if (this.#emitter) {
             this.#emitter.emit('session_auth:authentication_attempted', {
+                ctx: this.#ctx,
+                guardName: this.#name,
                 sessionId: session.sessionId,
             });
         }
@@ -248,8 +334,9 @@ export class SessionGuard {
              * storage
              */
             if (!providerUser) {
-                this.#authenticationFailed(new errors.E_INVALID_AUTH_SESSION(), session.sessionId);
+                this.#authenticationFailed(AuthenticationException.E_INVALID_AUTH_SESSION(), session.sessionId);
             }
+            debug('session_guard: marking user with id "%s" as authenticated', providerUser.getId());
             this.user = providerUser.getOriginal();
             this.isAuthenticated = true;
             this.isLoggedOut = false;
@@ -259,6 +346,8 @@ export class SessionGuard {
              */
             if (this.#emitter) {
                 this.#emitter.emit('session_auth:authentication_succeeded', {
+                    ctx: this.#ctx,
+                    guardName: this.#name,
                     sessionId: session.sessionId,
                     user: this.user,
                 });
@@ -280,7 +369,7 @@ export class SessionGuard {
          */
         const rememberMeCookie = this.#ctx.request.encryptedCookie(this.rememberMeKeyName);
         if (!rememberMeCookie || !this.#rememberMeTokenProvider) {
-            this.#authenticationFailed(new errors.E_INVALID_AUTH_SESSION(), session.sessionId);
+            this.#authenticationFailed(AuthenticationException.E_INVALID_AUTH_SESSION(), session.sessionId);
         }
         debug('session_guard: authenticating user from remember me cookie');
         /**
@@ -289,9 +378,12 @@ export class SessionGuard {
          * is missing or invalid
          */
         const decodedToken = RememberMeToken.decode(rememberMeCookie);
+        if (!decodedToken) {
+            this.#authenticationFailed(AuthenticationException.E_INVALID_AUTH_SESSION(), session.sessionId);
+        }
         const token = await this.#rememberMeTokenProvider.getTokenBySeries(decodedToken.series);
         if (!token || !token.verify(decodedToken.value)) {
-            this.#authenticationFailed(new errors.E_INVALID_AUTH_SESSION(), session.sessionId);
+            this.#authenticationFailed(AuthenticationException.E_INVALID_AUTH_SESSION(), session.sessionId);
         }
         debug('session_guard: found valid remember me token');
         /**
@@ -300,7 +392,7 @@ export class SessionGuard {
          */
         const providerUser = await this.#userProvider.findById(token.userId);
         if (!providerUser) {
-            this.#authenticationFailed(new errors.E_INVALID_AUTH_SESSION(), session.sessionId);
+            this.#authenticationFailed(AuthenticationException.E_INVALID_AUTH_SESSION(), session.sessionId);
         }
         /**
          * Finally, login the user from the remember me token
@@ -309,6 +401,7 @@ export class SessionGuard {
         debug('session_guard: marking user with id "%s" as logged in from remember me cookie', userId);
         session.put(this.sessionKeyName, userId);
         session.regenerate();
+        debug('session_guard: marking user with id "%s" as authenticated', userId);
         this.user = providerUser.getOriginal();
         this.isAuthenticated = true;
         this.isLoggedOut = false;
@@ -318,6 +411,8 @@ export class SessionGuard {
          */
         if (this.#emitter) {
             this.#emitter.emit('session_auth:authentication_succeeded', {
+                ctx: this.#ctx,
+                guardName: this.#name,
                 sessionId: session.sessionId,
                 user: this.user,
                 rememberMeToken: token,
@@ -370,11 +465,58 @@ export class SessionGuard {
             return true;
         }
         catch (error) {
-            if (error instanceof errors.E_INVALID_AUTH_SESSION ||
-                error instanceof errors.E_INVALID_AUTH_TOKEN) {
+            if (error instanceof AuthenticationException) {
                 return false;
             }
             throw error;
         }
     }
+    /**
+     * Logout user and revoke remember me token (if any)
+     */
+    async logout() {
+        debug('session_auth: logging out');
+        const session = this.#getSession();
+        /**
+         * Clear client side state
+         */
+        session.forget(this.sessionKeyName);
+        this.#ctx.response.clearCookie(this.rememberMeKeyName);
+        /**
+         * Notify the user has been logged out
+         */
+        if (this.#emitter) {
+            this.#emitter.emit('session_auth:logged_out', {
+                ctx: this.#ctx,
+                guardName: this.#name,
+                user: this.user || null,
+                sessionId: session.sessionId,
+            });
+        }
+        const rememberMeCookie = this.#ctx.request.encryptedCookie(this.rememberMeKeyName);
+        if (!rememberMeCookie || !this.#rememberMeTokenProvider) {
+            return;
+        }
+        debug('session_auth: decoding remember me token');
+        const decodedToken = RememberMeToken.decode(rememberMeCookie);
+        if (!decodedToken) {
+            return;
+        }
+        debug('session_auth: deleting remember me token');
+        await this.#rememberMeTokenProvider.deleteTokenBySeries(decodedToken.series);
+    }
+    /**
+     * Returns the session state for the user to be
+     * logged-in as a client
+     */
+    async authenticateAsClient(user) {
+        const providerUser = await this.#userProvider.createUserForGuard(user);
+        const userId = providerUser.getId();
+        debug('session_guard: returning client session for user id "%s"', userId);
+        return {
+            session: {
+                [this.sessionKeyName]: userId,
+            },
+        };
+    }
 }