@adonisjs/auth 8.2.3 → 9.0.0-1

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

@@ -0,0 +1,454 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { RuntimeException } from '@poppinss/utils';
+import debug from '../../auth/debug.js';
+import { RememberMeToken } from './token.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.
+ */
+export class SessionGuard {
+    /**
+     * A unique name for the guard. It is used for prefixing
+     * session data and remember me cookies
+     */
+    #name;
+    /**
+     * Reference to the current HTTP context
+     */
+    #ctx;
+    /**
+     * Configuration
+     */
+    #config;
+    /**
+     * Provider to lookup user details
+     */
+    #userProvider;
+    /**
+     * The remember me tokens provider to use to persist
+     * remember me tokens
+     */
+    #rememberMeTokenProvider;
+    /**
+     * Emitter to emit events
+     */
+    #emitter;
+    /**
+     * Driver name of the guard
+     */
+    driverName = 'session';
+    /**
+     * Whether or not the authentication has been attempted
+     * during the current request
+     */
+    authenticationAttempted = false;
+    /**
+     * Find if the user has been logged out during
+     * the current request
+     */
+    isLoggedOut = false;
+    /**
+     * A boolean to know if the current request has
+     * been authenticated
+     */
+    isAuthenticated = false;
+    /**
+     * A boolean to know if the current request is authenticated
+     * using the "rememember_me" token.
+     */
+    viaRemember = false;
+    /**
+     * Reference to an instance of the authenticated or logged-in
+     * user. The value only exists after calling one of the
+     * following methods.
+     *
+     * - login
+     * - loginViaId
+     * - attempt
+     * - authenticate
+     *
+     * You can use the "getUserOrFail" method to throw an exception if
+     * the request is not authenticated.
+     */
+    user;
+    /**
+     * The key used to store the logged-in user id inside
+     * session
+     */
+    get sessionKeyName() {
+        return `auth_${this.#name}`;
+    }
+    /**
+     * The key used to store the remember me token cookie
+     */
+    get rememberMeKeyName() {
+        return `remember_${this.#name}`;
+    }
+    constructor(name, config, ctx, userProvider) {
+        this.#name = name;
+        this.#ctx = ctx;
+        this.#config = config;
+        this.#userProvider = userProvider;
+    }
+    /**
+     * Returns an instance of the tokens provider, ensuring
+     * it has been configured
+     */
+    #getTokenProvider() {
+        if (!this.#rememberMeTokenProvider) {
+            throw new RuntimeException('Cannot use "rememberMe" feature. Please configure the tokens provider inside config/auth file');
+        }
+        return this.#rememberMeTokenProvider;
+    }
+    /**
+     * Returns the session instance for the given request,
+     * ensuring the property exists
+     */
+    #getSession() {
+        if (!('session' in this.#ctx)) {
+            throw new RuntimeException('Cannot login user. Make sure you have installed the "@adonisjs/session" package and configured its middleware');
+        }
+        return this.#ctx.session;
+    }
+    /**
+     * Notifies about authentication failure and throws the exception
+     */
+    #authenticationFailed(error, sessionId) {
+        if (this.#emitter) {
+            this.#emitter.emit('session_auth:authentication_failed', {
+                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', {
+                error,
+                user,
+            });
+        }
+        throw error;
+    }
+    /**
+     * Register the remember me tokens provider to create
+     * remember me tokens during user login.
+     *
+     * Note: This method only registers the remember me tokens provider
+     * and does not enable them. You must pass "rememberMe = true" during
+     * the "login" method call.
+     */
+    withRememberMeTokens(tokensProvider) {
+        this.#rememberMeTokenProvider = tokensProvider;
+        return this;
+    }
+    /**
+     * Register an event emitter to listen for global events for
+     * authentication lifecycle.
+     */
+    withEmitter(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_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', {
+                uid,
+                user,
+            });
+        }
+        return user;
+    }
+    /**
+     * Attempt to login a user after verifying their
+     * credentials.
+     */
+    async attempt(uid, password) {
+        const user = await this.verifyCredentials(uid, password);
+        return this.login(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
+     */
+    async loginViaId(id) {
+        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());
+    }
+    /**
+     * Login a user using the user object.
+     */
+    async login(user, remember = false) {
+        if (this.#emitter) {
+            this.#emitter.emit('session_auth:login_attempted', { user });
+        }
+        const providerUser = await this.#userProvider.createUserForGuard(user);
+        const session = this.#getSession();
+        /**
+         * Create session and recycle the session id
+         */
+        const userId = providerUser.getId();
+        debug('session_guard: marking user with id "%s" as logged-in', userId);
+        session.put(this.sessionKeyName, userId);
+        session.regenerate();
+        /**
+         * Manage remember me cookie
+         */
+        let token;
+        if (remember) {
+            const tokenProvider = this.#getTokenProvider();
+            /**
+             * Create a token
+             */
+            token = RememberMeToken.create(providerUser.getId(), this.#config.rememberMeTokenAge || '2years');
+            /**
+             * Persist remember me token inside the database
+             */
+            await tokenProvider.createToken(token);
+            /**
+             * Drop token value inside the cookie
+             */
+            debug('session_guard: creating remember me cookie');
+            this.#ctx.response.encryptedCookie(this.rememberMeKeyName, token.value, {
+                maxAge: this.#config.rememberMeTokenAge,
+                httpOnly: true,
+            });
+        }
+        else {
+            this.#ctx.response.clearCookie(this.rememberMeKeyName);
+        }
+        /**
+         * Toggle properties to mark user as logged-in
+         */
+        this.user = user;
+        this.isLoggedOut = false;
+        /**
+         * Notify the login is successful
+         */
+        if (this.#emitter) {
+            this.#emitter.emit('session_auth:login_succeeded', {
+                user,
+                sessionId: session.sessionId,
+                rememberMeToken: token,
+            });
+        }
+        return user;
+    }
+    /**
+     * Authenticates the HTTP request to ensure the
+     * user is logged-in
+     */
+    async authenticate() {
+        if (this.authenticationAttempted) {
+            return this.getUserOrFail();
+        }
+        this.authenticationAttempted = true;
+        const session = this.#getSession();
+        /**
+         * Notify we are starting authentication process
+         */
+        if (this.#emitter) {
+            this.#emitter.emit('session_auth:authentication_attempted', {
+                sessionId: session.sessionId,
+            });
+        }
+        /**
+         * Check if there is a user id inside the session store.
+         * If yes, fetch the user from the persistent storage
+         * and mark them as logged-in
+         */
+        const loggedInUserId = session.get(this.sessionKeyName);
+        if (loggedInUserId) {
+            debug('session_guard: authenticating user from session');
+            const providerUser = await this.#userProvider.findById(loggedInUserId);
+            /**
+             * Throw error when user is not found inside the persistent
+             * storage
+             */
+            if (!providerUser) {
+                this.#authenticationFailed(AuthenticationException.E_INVALID_AUTH_SESSION(), session.sessionId);
+            }
+            this.user = providerUser.getOriginal();
+            this.isAuthenticated = true;
+            this.isLoggedOut = false;
+            this.viaRemember = false;
+            /**
+             * Authentication was successful
+             */
+            if (this.#emitter) {
+                this.#emitter.emit('session_auth:authentication_succeeded', {
+                    sessionId: session.sessionId,
+                    user: this.user,
+                });
+            }
+            return this.user;
+        }
+        /**
+         * Otherwise check for remember me cookie and attempt
+         * to login user via that.
+         *
+         * Also, if the remember me token provider is not registered,
+         * we will silently ignore the remember me cookie and
+         * throw invalid session exception
+         *
+         * This is because, sometimes an app might use the remember me
+         * tokens initially and then back out and stop using them. In
+         * that case, we should not fail authentication attempts, just
+         * ignore the remember me cookie.
+         */
+        const rememberMeCookie = this.#ctx.request.encryptedCookie(this.rememberMeKeyName);
+        if (!rememberMeCookie || !this.#rememberMeTokenProvider) {
+            this.#authenticationFailed(AuthenticationException.E_INVALID_AUTH_SESSION(), session.sessionId);
+        }
+        debug('session_guard: authenticating user from remember me cookie');
+        /**
+         * Decode remember me cookie and check for its existence inside
+         * the database. Throw invalid session exception when token
+         * 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(AuthenticationException.E_INVALID_AUTH_SESSION(), session.sessionId);
+        }
+        debug('session_guard: found valid remember me token');
+        /**
+         * Find user for whom the token was created. Throw invalid
+         * session exception when the user is missing
+         */
+        const providerUser = await this.#userProvider.findById(token.userId);
+        if (!providerUser) {
+            this.#authenticationFailed(AuthenticationException.E_INVALID_AUTH_SESSION(), session.sessionId);
+        }
+        /**
+         * Finally, login the user from the remember me token
+         */
+        const userId = providerUser.getId();
+        debug('session_guard: marking user with id "%s" as logged in from remember me cookie', userId);
+        session.put(this.sessionKeyName, userId);
+        session.regenerate();
+        this.user = providerUser.getOriginal();
+        this.isAuthenticated = true;
+        this.isLoggedOut = false;
+        this.viaRemember = true;
+        /**
+         * Authentication was successful via remember me token
+         */
+        if (this.#emitter) {
+            this.#emitter.emit('session_auth:authentication_succeeded', {
+                sessionId: session.sessionId,
+                user: this.user,
+                rememberMeToken: token,
+            });
+        }
+        /**
+         * ----------------------------------------------------------------
+         * User is logged in now. From here on we are refreshing the
+         * remember me token.
+         * ----------------------------------------------------------------
+         *
+         * Here we refresh the token value inside the db when the
+         * current remember_me token is older than 1 minute.
+         *
+         * Otherwise, we re-use the same token. This is avoid race-conditions
+         * when parallel requests uses the remember_me token to authenticate
+         * the user.
+         *
+         * Finally, we will update remember_me cookie lifespan in both the cases.
+         * Be it updated the token inside databse, or not.
+         */
+        const currentTime = new Date();
+        const updatedAtWithBuffer = new Date(token.updatedAt);
+        updatedAtWithBuffer.setSeconds(updatedAtWithBuffer.getSeconds() + 60);
+        if (updatedAtWithBuffer < currentTime) {
+            const newToken = RememberMeToken.create(token.userId, this.#config.rememberMeTokenAge || '2years');
+            await this.#rememberMeTokenProvider.updateTokenBySeries(token.series, newToken.hash, newToken.expiresAt);
+            this.#ctx.response.encryptedCookie(this.rememberMeKeyName, newToken.value, {
+                maxAge: this.#config.rememberMeTokenAge,
+                httpOnly: true,
+            });
+        }
+        else {
+            this.#ctx.response.encryptedCookie(this.rememberMeKeyName, rememberMeCookie, {
+                maxAge: this.#config.rememberMeTokenAge,
+                httpOnly: true,
+            });
+        }
+        return this.user;
+    }
+    /**
+     * 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;
+        }
+    }
+}

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

@@ -0,0 +1,3 @@
+export { SessionGuard } from './guard.js';
+export { RememberMeToken } from './token.js';
+export { sessionGuard, tokensProvider } from './define_config.js';

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

@@ -0,0 +1,11 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+export { SessionGuard } from './guard.js';
+export { RememberMeToken } from './token.js';
+export { sessionGuard, tokensProvider } from './define_config.js';

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

@@ -0,0 +1,57 @@
+import { Token } from '../../core/token.js';
+/**
+ * Remember me token represents a remember me token created
+ * for a peristed login flow.
+ */
+export declare class RememberMeToken extends Token {
+    /**
+     * Reference to the user id for whom the token
+     * is generated
+     */
+    userId: string | number;
+    /**
+     * Series is a random number stored inside the database as it is
+     */
+    series: string;
+    /**
+     * Value is a random number only available at the time of issuing
+     * the token. Afterwards, the value is undefined.
+     */
+    value: string | undefined;
+    /**
+     * Hash reference to the token hash
+     */
+    hash: string;
+    /**
+     * Static name for the token to uniquely identify a
+     * bucket of tokens
+     */
+    readonly type: 'remember_me_token';
+    /**
+     * Timestamp at which the token will expire
+     */
+    expiresAt: Date;
+    constructor(
+    /**
+     * Reference to the user id for whom the token
+     * is generated
+     */
+    userId: string | number, 
+    /**
+     * Series is a random number stored inside the database as it is
+     */
+    series: string, 
+    /**
+     * Value is a random number only available at the time of issuing
+     * the token. Afterwards, the value is undefined.
+     */
+    value: string | undefined, 
+    /**
+     * Hash reference to the token hash
+     */
+    hash: string);
+    /**
+     * Create remember me token instance for a user
+     */
+    static create(userId: string | number, expiry: string | number, size?: number): RememberMeToken;
+}

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

@@ -0,0 +1,58 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { Token } from '../../core/token.js';
+/**
+ * Remember me token represents a remember me token created
+ * for a peristed login flow.
+ */
+export class RememberMeToken extends Token {
+    userId;
+    series;
+    value;
+    hash;
+    /**
+     * Static name for the token to uniquely identify a
+     * bucket of tokens
+     */
+    type = 'remember_me_token';
+    constructor(
+    /**
+     * Reference to the user id for whom the token
+     * is generated
+     */
+    userId, 
+    /**
+     * Series is a random number stored inside the database as it is
+     */
+    series, 
+    /**
+     * Value is a random number only available at the time of issuing
+     * the token. Afterwards, the value is undefined.
+     */
+    value, 
+    /**
+     * Hash reference to the token hash
+     */
+    hash) {
+        super(series, value, hash);
+        this.userId = userId;
+        this.series = series;
+        this.value = value;
+        this.hash = hash;
+    }
+    /**
+     * Create remember me token instance for a user
+     */
+    static create(userId, expiry, size) {
+        const { series, value, hash } = this.seed(size);
+        const token = new RememberMeToken(userId, series, value, hash);
+        token.setExpiry(expiry);
+        return token;
+    }
+}

package/build/src/guards/session/token_providers/main.d.ts

@@ -0,0 +1,33 @@
+import { RememberMeToken } from '../token.js';
+import type { RememberMeProviderContract } from '../types.js';
+import { DatabaseTokenProvider } from '../../../core/token_providers/database.js';
+/**
+ * Remember me token provider to persist tokens inside the database
+ * using db query builder.
+ */
+export declare class DatabaseRememberTokenProvider extends DatabaseTokenProvider<RememberMeToken> implements RememberMeProviderContract {
+    /**
+     * Prepares a token from the database result
+     */
+    protected prepareToken(dbRow: {
+        series: string;
+        user_id: string | number;
+        type: string;
+        token: string;
+        created_at: Date;
+        updated_at: Date;
+        expires_at: Date | null;
+    }): RememberMeToken;
+    /**
+     * Converts the remember me token into a database row
+     */
+    protected parseToken(token: RememberMeToken): {
+        series: string;
+        user_id: string | number;
+        type: string;
+        token: string;
+        created_at: Date;
+        updated_at: Date;
+        expires_at: Date | null;
+    };
+}

package/build/src/guards/session/token_providers/main.js

@@ -0,0 +1,42 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { RememberMeToken } from '../token.js';
+import { DatabaseTokenProvider } from '../../../core/token_providers/database.js';
+/**
+ * Remember me token provider to persist tokens inside the database
+ * using db query builder.
+ */
+export class DatabaseRememberTokenProvider extends DatabaseTokenProvider {
+    /**
+     * Prepares a token from the database result
+     */
+    prepareToken(dbRow) {
+        const token = new RememberMeToken(dbRow.user_id, dbRow.series, undefined, dbRow.token);
+        if (dbRow.expires_at) {
+            token.expiresAt = dbRow.expires_at;
+        }
+        token.createdAt = dbRow.created_at;
+        token.updatedAt = dbRow.updated_at;
+        return token;
+    }
+    /**
+     * Converts the remember me token into a database row
+     */
+    parseToken(token) {
+        return {
+            series: token.series,
+            user_id: token.userId,
+            type: token.type,
+            token: token.hash,
+            created_at: token.createdAt,
+            updated_at: token.updatedAt,
+            expires_at: token.expiresAt,
+        };
+    }
+}