@adonisjs/auth 9.0.0-0 → 9.0.0-10

package/build/src/auth/errors.js

@@ -6,12 +6,196 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-import { createError } from '@poppinss/utils';
+import { Exception } from '@poppinss/utils';
 /**
- * Invalid token provided
+ * Authentication exception is raised when an attempt is
+ * made to authenticate an HTTP request
  */
-export const E_INVALID_AUTH_TOKEN = createError('Invalid or expired token value', 'E_INVALID_AUTH_TOKEN', 401);
+export class AuthenticationException extends Exception {
+    static status = 401;
+    static code = 'E_UNAUTHORIZED_ACCESS';
+    /**
+     * Raises authentication exception when session guard
+     * is unable to authenticate the request
+     */
+    static E_INVALID_AUTH_SESSION() {
+        return new AuthenticationException('Invalid or expired authentication session', {
+            code: 'E_INVALID_AUTH_SESSION',
+            status: 401,
+            guardDriverName: 'session',
+        });
+    }
+    /**
+     * Raises authentication exception when session guard
+     * is unable to authenticate the request
+     */
+    static E_INVALID_BASIC_AUTH_CREDENTIALS() {
+        return new AuthenticationException('Invalid basic auth credentials', {
+            code: 'E_INVALID_BASIC_AUTH_CREDENTIALS',
+            status: 401,
+            guardDriverName: 'basic_auth',
+        });
+    }
+    guardDriverName;
+    redirectTo;
+    identifier = 'auth.authenticate';
+    constructor(message, options) {
+        super(message, options);
+        this.guardDriverName = options.guardDriverName;
+        this.redirectTo = options.redirectTo;
+    }
+    /**
+     * Returns the message to be sent in the HTTP response.
+     * Feel free to override this method and return a custom
+     * response.
+     */
+    getResponseMessage(error, ctx) {
+        if ('i18n' in ctx) {
+            return ctx.i18n.t(error.identifier, {}, error.message);
+        }
+        return error.message;
+    }
+    /**
+     * A collection of authentication exception
+     * renderers to render the exception to a
+     * response.
+     *
+     * The collection is a key-value pair, where the
+     * key is the guard driver name and value is
+     * a factory function to respond to the
+     * request.
+     */
+    renderers = {
+        session: (message, error, ctx) => {
+            switch (ctx.request.accepts(['html', 'application/vnd.api+json', 'json'])) {
+                case 'html':
+                case null:
+                    ctx.session.flashExcept(['_csrf']);
+                    ctx.session.flashErrors({ [error.identifier]: [message] });
+                    ctx.response.redirect(error.redirectTo || '/', true);
+                    break;
+                case 'json':
+                    ctx.response.status(error.status).send({
+                        errors: [
+                            {
+                                message,
+                            },
+                        ],
+                    });
+                    break;
+                case 'application/vnd.api+json':
+                    ctx.response.status(error.status).send({
+                        errors: [
+                            {
+                                code: error.identifier,
+                                title: message,
+                            },
+                        ],
+                    });
+                    break;
+            }
+        },
+        basic_auth: (message, _, ctx) => {
+            ctx.response
+                .status(this.status)
+                .header('WWW-Authenticate', `Basic realm="Authenticate", charset="UTF-8"`)
+                .send(message);
+        },
+    };
+    /**
+     * Self handles the auth exception and converts it to an
+     * HTTP response
+     */
+    async handle(error, ctx) {
+        const renderer = this.renderers[this.guardDriverName];
+        const message = error.getResponseMessage(error, ctx);
+        if (!renderer) {
+            return ctx.response.status(error.status).send(message);
+        }
+        return renderer(message, error, ctx);
+    }
+}
 /**
- * The user session is invalid
+ * Invalid credentials exception is raised when unable
+ * to verify user credentials during login
  */
-export const E_INVALID_AUTH_SESSION = createError('Invalid or expired authentication session', 'E_INVALID_AUTH_SESSION', 401);
+export class InvalidCredentialsException extends Exception {
+    static message = 'Invalid credentials';
+    static code = 'E_INVALID_CREDENTIALS';
+    static status = 400;
+    static E_INVALID_CREDENTIALS(guardDriverName) {
+        return new InvalidCredentialsException(InvalidCredentialsException.message, {
+            guardDriverName,
+        });
+    }
+    guardDriverName;
+    identifier = 'auth.login';
+    constructor(message, options) {
+        super(message, options);
+        this.guardDriverName = options.guardDriverName;
+    }
+    /**
+     * Returns the message to be sent in the HTTP response.
+     * Feel free to override this method and return a custom
+     * response.
+     */
+    getResponseMessage(error, ctx) {
+        if ('i18n' in ctx) {
+            return ctx.i18n.t(this.identifier, {}, error.message);
+        }
+        return error.message;
+    }
+    /**
+     * A collection of authentication exception
+     * renderers to render the exception to a
+     * response.
+     *
+     * The collection is a key-value pair, where the
+     * key is the guard driver name and value is
+     * a factory function to respond to the
+     * request.
+     */
+    renderers = {
+        session: (message, error, ctx) => {
+            switch (ctx.request.accepts(['html', 'application/vnd.api+json', 'json'])) {
+                case 'html':
+                case null:
+                    ctx.session.flashExcept(['_csrf']);
+                    ctx.session.flashErrors({ [this.identifier]: [message] });
+                    ctx.response.redirect().withQs().back();
+                    break;
+                case 'json':
+                    ctx.response.status(error.status).send({
+                        errors: [
+                            {
+                                message: message,
+                            },
+                        ],
+                    });
+                    break;
+                case 'application/vnd.api+json':
+                    ctx.response.status(error.status).send({
+                        errors: [
+                            {
+                                code: this.identifier,
+                                title: message,
+                            },
+                        ],
+                    });
+                    break;
+            }
+        },
+    };
+    /**
+     * Self handles the auth exception and converts it to an
+     * HTTP response
+     */
+    async handle(error, ctx) {
+        const renderer = this.renderers[this.guardDriverName];
+        const message = this.getResponseMessage(error, ctx);
+        if (!renderer) {
+            return ctx.response.status(error.status).send(message);
+        }
+        return renderer(message, error, ctx);
+    }
+}

package/build/src/auth/middleware/initialize_auth_middleware.d.ts

@@ -0,0 +1,18 @@
+import auth from '@adonisjs/auth/services/main';
+import type { HttpContext } from '@adonisjs/core/http';
+import type { NextFn } from '@adonisjs/core/types/http';
+/**
+ * The "InitializeAuthMiddleware" is used to create a request
+ * specific authenticator instance for every HTTP request.
+ *
+ * This middleware does not protect routes from unauthenticated
+ * users. Please use the "auth" middleware for that.
+ */
+export default class InitializeAuthMiddleware {
+    handle(ctx: HttpContext, next: NextFn): Promise<any>;
+}
+declare module '@adonisjs/core/http' {
+    interface HttpContext {
+        auth: ReturnType<(typeof auth)['createAuthenticator']>;
+    }
+}

package/build/src/auth/middleware/initialize_auth_middleware.js

@@ -0,0 +1,25 @@
+/// <reference types="@adonisjs/core/providers/edge_provider" />
+import auth from '@adonisjs/auth/services/main';
+/**
+ * The "InitializeAuthMiddleware" is used to create a request
+ * specific authenticator instance for every HTTP request.
+ *
+ * This middleware does not protect routes from unauthenticated
+ * users. Please use the "auth" middleware for that.
+ */
+export default class InitializeAuthMiddleware {
+    async handle(ctx, next) {
+        /**
+         * Initialize the authenticator for the current HTTP
+         * request
+         */
+        ctx.auth = auth.createAuthenticator(ctx);
+        /**
+         * Sharing authenticator with templates
+         */
+        if ('view' in ctx) {
+            ctx.view.share({ auth: ctx.auth });
+        }
+        return next();
+    }
+}

package/build/src/auth/plugins/japa/api_client.d.ts

@@ -0,0 +1,32 @@
+import type { PluginFn } from '@japa/runner/types';
+import type { ApplicationService } from '@adonisjs/core/types';
+import type { Authenticators, GuardContract, GuardFactory } from '../../types.js';
+declare module '@japa/api-client' {
+    interface ApiRequest {
+        authData: {
+            guard: string;
+            user: unknown;
+        };
+        /**
+         * Login a user using the default authentication
+         * guard when making an API call
+         */
+        loginAs(user: {
+            [K in keyof Authenticators]: Authenticators[K] extends GuardFactory ? ReturnType<Authenticators[K]> extends GuardContract<infer A> ? A : never : never;
+        }): this;
+        /**
+         * Define the authentication guard for login
+         */
+        withGuard<K extends keyof Authenticators, Self extends ApiRequest>(this: Self, guard: K): {
+            /**
+             * Login a user using a specific auth guard
+             */
+            loginAs(user: Authenticators[K] extends GuardFactory ? ReturnType<Authenticators[K]> extends GuardContract<infer A> ? A : never : never): Self;
+        };
+    }
+}
+/**
+ * Auth API client to authenticate users when making
+ * HTTP requests using the Japa API client
+ */
+export declare const authApiClient: (app: ApplicationService) => PluginFn;

package/build/src/auth/plugins/japa/api_client.js

@@ -0,0 +1,63 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { ApiClient, ApiRequest } from '@japa/api-client';
+import debug from '../../debug.js';
+/**
+ * Auth API client to authenticate users when making
+ * HTTP requests using the Japa API client
+ */
+export const authApiClient = (app) => {
+    const pluginFn = function () {
+        debug('installing auth api client plugin');
+        ApiRequest.macro('loginAs', function (user) {
+            this.authData = {
+                guard: '__default__',
+                user: user,
+            };
+            return this;
+        });
+        ApiRequest.macro('withGuard', function (guard) {
+            return {
+                loginAs: (user) => {
+                    this.authData = {
+                        guard,
+                        user: user,
+                    };
+                    return this;
+                },
+            };
+        });
+        /**
+         * Hook into the request and login the user
+         */
+        ApiClient.setup(async (request) => {
+            const auth = await app.container.make('auth.manager');
+            const authData = request['authData'];
+            if (!authData) {
+                return;
+            }
+            const client = auth.createAuthenticatorClient();
+            const guard = authData.guard === '__default__' ? client.use() : client.use(authData.guard);
+            const requestData = await guard.authenticateAsClient(authData.user);
+            if (requestData.headers) {
+                debug('defining headers with api client request %O', requestData.headers);
+                request.headers(requestData.headers);
+            }
+            if (requestData.session) {
+                debug('defining session with api client request %O', requestData.session);
+                request.withSession(requestData.session);
+            }
+            if (requestData.cookies) {
+                debug('defining session with api client request %O', requestData.session);
+                request.cookies(requestData.cookies);
+            }
+        });
+    };
+    return pluginFn;
+};

package/build/src/auth/plugins/japa/browser_client.d.ts

@@ -0,0 +1,25 @@
+import type { PluginFn } from '@japa/runner/types';
+import type { ApplicationService } from '@adonisjs/core/types';
+import type { Authenticators, GuardContract, GuardFactory } from '../../types.js';
+declare module 'playwright' {
+    interface BrowserContext {
+        /**
+         * Login a user using the default authentication
+         * guard when using the browser context to
+         * make page visits
+         */
+        loginAs(user: {
+            [K in keyof Authenticators]: Authenticators[K] extends GuardFactory ? ReturnType<Authenticators[K]> extends GuardContract<infer A> ? A : never : never;
+        }): Promise<void>;
+        /**
+         * Define the authentication guard for login
+         */
+        withGuard<K extends keyof Authenticators>(guard: K): {
+            /**
+             * Login a user using a specific auth guard
+             */
+            loginAs(user: Authenticators[K] extends GuardFactory ? ReturnType<Authenticators[K]> extends GuardContract<infer A> ? A : never : never): Promise<void>;
+        };
+    }
+}
+export declare const authBrowserClient: (app: ApplicationService) => PluginFn;

package/build/src/auth/plugins/japa/browser_client.js

@@ -0,0 +1,64 @@
+/*
+ * @adoniss/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+/// <reference types="@japa/plugin-adonisjs" />
+/// <reference types="@adonisjs/session/plugins/browser_client" />
+import { RuntimeException } from '@poppinss/utils';
+import { decoratorsCollection } from '@japa/browser-client';
+import debug from '../../debug.js';
+export const authBrowserClient = (app) => {
+    const pluginFn = async function () {
+        debug('installing auth browser client plugin');
+        const auth = await app.container.make('auth.manager');
+        decoratorsCollection.register({
+            context(context) {
+                context.withGuard = function (guardName) {
+                    return {
+                        async loginAs(user) {
+                            const client = auth.createAuthenticatorClient();
+                            const guard = client.use(guardName);
+                            const requestData = await guard.authenticateAsClient(user);
+                            if (requestData.headers) {
+                                throw new RuntimeException(`Cannot use "${guard.driverName}" guard with browser client`);
+                            }
+                            if (requestData.cookies) {
+                                debug('defining cookies with browser context %O', requestData.cookies);
+                                Object.keys(requestData.cookies).forEach((cookie) => {
+                                    context.setCookie(cookie, requestData.cookies[cookie]);
+                                });
+                            }
+                            if (requestData.session) {
+                                debug('defining session with browser context %O', requestData.session);
+                                context.setSession(requestData.session);
+                            }
+                        },
+                    };
+                };
+                context.loginAs = async function (user) {
+                    const client = auth.createAuthenticatorClient();
+                    const guard = client.use();
+                    const requestData = await guard.authenticateAsClient(user);
+                    if (requestData.headers) {
+                        throw new RuntimeException(`Cannot use "${guard.driverName}" guard with browser client`);
+                    }
+                    if (requestData.cookies) {
+                        debug('defining cookies with browser context %O', requestData.cookies);
+                        Object.keys(requestData.cookies).forEach((cookie) => {
+                            context.setCookie(cookie, requestData.cookies[cookie]);
+                        });
+                    }
+                    if (requestData.session) {
+                        debug('defining session with browser context %O', requestData.session);
+                        context.setSession(requestData.session);
+                    }
+                };
+            },
+        });
+    };
+    return pluginFn;
+};

package/build/src/auth/types.d.ts

@@ -1,25 +1,63 @@
-import type { Emitter } from '@adonisjs/core/events';
 import type { HttpContext } from '@adonisjs/core/http';
 import type { ApplicationService, ConfigProvider } from '@adonisjs/core/types';
 import type { AuthManager } from './auth_manager.js';
 import type { GUARD_KNOWN_EVENTS } from './symbols.js';
+/**
+ * The client response for authentication.
+ */
+export interface AuthClientResponse {
+    headers?: Record<string, any>;
+    cookies?: Record<string, any>;
+    session?: Record<string, any>;
+}
 /**
  * A set of properties a guard must implement.
  */
 export interface GuardContract<User> {
     /**
-     * Reference to the user type
+     * Reference to the currently authenticated user
      */
     user?: User;
+    /**
+     * Returns logged-in user or throws an exception
+     */
+    getUserOrFail(): User;
+    /**
+     * A boolean to know if the current request has
+     * been authenticated
+     */
+    isAuthenticated: boolean;
+    /**
+     * Whether or not the authentication has been attempted
+     * during the current request
+     */
+    authenticationAttempted: boolean;
+    /**
+     * Check if the current request has been
+     * authenticated without throwing an
+     * exception
+     */
+    check(): Promise<boolean>;
+    /**
+     * The method is used to authenticate the user as
+     * client. This method should return cookies,
+     * headers, or session state.
+     */
+    authenticateAsClient(user: User): Promise<AuthClientResponse>;
+    /**
+     * Authenticates the current request and throws
+     * an exception if the request is not authenticated.
+     */
+    authenticate(): Promise<User>;
+    /**
+     * A unique name for the guard driver
+     */
+    driverName: string;
     /**
      * Aymbol for infer the events emitted by a specific
      * guard
      */
     [GUARD_KNOWN_EVENTS]: unknown;
-    /**
-     * Accept an instance of the emitter to emit events
-     */
-    withEmitter(emitter: Emitter<any>): this;
 }
 /**
  * The authenticator guard factory method is called by the
@@ -36,13 +74,26 @@ export interface Authenticators {
 /**
  * Infer authenticators from the auth config
  */
-export type InferAuthenticators<Config extends ConfigProvider<unknown>> = Awaited<ReturnType<Config['resolver']>>;
+export type InferAuthenticators<Config extends ConfigProvider<{
+    default: unknown;
+    guards: unknown;
+}>> = Awaited<ReturnType<Config['resolver']>>['guards'];
+/**
+ * Helper to convert union to intersection
+ */
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Infer events based upon the configure authenticators
+ */
+export type InferAuthEvents<KnownAuthenticators extends Record<string, GuardFactory>> = UnionToIntersection<{
+    [K in keyof KnownAuthenticators]: ReturnType<KnownAuthenticators[K]>[typeof GUARD_KNOWN_EVENTS];
+}[keyof KnownAuthenticators]>;
 /**
  * Auth service is a singleton instance of the AuthManager
  * configured using the config stored within the user
  * app.
  */
-export interface AuthService extends AuthManager<Authenticators extends GuardFactory ? Authenticators : never> {
+export interface AuthService extends AuthManager<Authenticators extends Record<string, GuardFactory> ? Authenticators : never> {
 }
 /**
  * Config provider for exporting guard
@@ -50,3 +101,4 @@ export interface AuthService extends AuthManager<Authenticators extends GuardFac
 export type GuardConfigProvider<Guard extends GuardFactory> = {
     resolver: (name: string, app: ApplicationService) => Promise<Guard>;
 };
+export {};

package/build/src/core/token.d.ts

@@ -78,8 +78,11 @@ export declare abstract class Token implements TokenContract {
     /**
      * Decodes a publicly shared token and return the series
      * and the token value from it.
+     *
+     * Returns null when unable to decode the token because of
+     * invalid format or encoding.
      */
-    static decode(value: string): {
+    static decode(value: string): null | {
         series: string;
         value: string;
     };

package/build/src/core/token.js

@@ -9,7 +9,6 @@
 import { createHash } from 'node:crypto';
 import string from '@adonisjs/core/helpers/string';
 import { base64, safeEqual } from '@adonisjs/core/helpers';
-import * as errors from '../auth/errors.js';
 /**
  * A token represents an opaque token issued to a client
  * to perform a specific task.
@@ -93,16 +92,19 @@ export class Token {
     /**
      * Decodes a publicly shared token and return the series
      * and the token value from it.
+     *
+     * Returns null when unable to decode the token because of
+     * invalid format or encoding.
      */
     static decode(value) {
         const [series, ...tokenValue] = value.split('.');
         if (!series || tokenValue.length === 0) {
-            throw new errors.E_INVALID_AUTH_TOKEN();
+            return null;
         }
         const decodedSeries = base64.urlDecode(series);
         const decodedValue = base64.urlDecode(tokenValue.join('.'));
         if (!decodedSeries || !decodedValue) {
-            throw new errors.E_INVALID_AUTH_TOKEN();
+            return null;
         }
         return {
             series: decodedSeries,

package/build/src/core/token_providers/database.d.ts

@@ -11,7 +11,7 @@ type DatabaseTokenRow = {
     created_at: Date;
     updated_at: Date;
     expires_at: Date | null;
-};
+} & Record<string, any>;
 /**
  * A generic implementation to read tokens from the database
  */

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

@@ -0,0 +1,16 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { ConfigProvider } from '@adonisjs/core/types';
+import type { GuardConfigProvider } from '../../auth/types.js';
+import type { UserProviderContract } from '../../core/types.js';
+import { BasicAuthGuard } from './guard.js';
+/**
+ * Helper function to configure the basic auth guard for
+ * authentication.
+ *
+ * This method returns a config builder, which internally
+ * returns a factory function to construct a guard
+ * during HTTP requests.
+ */
+export declare function basicAuthGuard<UserProvider extends UserProviderContract<unknown>>(config: {
+    provider: ConfigProvider<UserProvider>;
+}): GuardConfigProvider<(ctx: HttpContext) => BasicAuthGuard<UserProvider>>;

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

@@ -0,0 +1,38 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { configProvider } from '@adonisjs/core';
+import { RuntimeException } from '@poppinss/utils';
+import { BasicAuthGuard } from './guard.js';
+/**
+ * Helper function to configure the basic auth guard for
+ * authentication.
+ *
+ * This method returns a config builder, which internally
+ * returns a factory function to construct a guard
+ * during HTTP requests.
+ */
+export function basicAuthGuard(config) {
+    return {
+        async resolver(guardName, app) {
+            const provider = await configProvider.resolve(app, config.provider);
+            if (!provider) {
+                throw new RuntimeException(`Invalid user provider defined on "${guardName}" guard`);
+            }
+            const emitter = await app.container.make('emitter');
+            /**
+             * Factory function needed by Authenticator to switch
+             * between guards and perform authentication
+             */
+            return (ctx) => {
+                const guard = new BasicAuthGuard(guardName, ctx, provider);
+                return guard.setEmitter(emitter);
+            };
+        },
+    };
+}