@adonisjs/auth 8.2.3 → 9.0.0-1

package/build/src/auth/authenticator.js

@@ -0,0 +1,122 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import debug from './debug.js';
+import { AuthenticationException } from './errors.js';
+/**
+ * Authenticator is an HTTP request specific implementation for using
+ * guards to login users and authenticate requests.
+ */
+export class Authenticator {
+    /**
+     * Name of the guard using which the request has
+     * been authenticated
+     */
+    #authenticatedViaGuard;
+    /**
+     * Reference to HTTP context
+     */
+    #ctx;
+    /**
+     * Registered guards
+     */
+    #config;
+    /**
+     * Cache of guards created during the HTTP request
+     */
+    #guardsCache = {};
+    /**
+     * Name of the default guard
+     */
+    get defaultGuard() {
+        return this.#config.default;
+    }
+    /**
+     * Reference to the guard using which the current
+     * request has been authenticated.
+     */
+    get authenticatedViaGuard() {
+        return this.#authenticatedViaGuard;
+    }
+    /**
+     * A boolean to know if the current request has
+     * been authenticated
+     */
+    get isAuthenticated() {
+        return this.use(this.#authenticatedViaGuard || this.defaultGuard).isAuthenticated;
+    }
+    /**
+     * Reference to the currently authenticated user
+     */
+    get user() {
+        return this.use(this.#authenticatedViaGuard || this.defaultGuard).user;
+    }
+    /**
+     * Whether or not the authentication has been attempted
+     * during the current request
+     */
+    get authenticationAttempted() {
+        return this.use(this.#authenticatedViaGuard || this.defaultGuard).authenticationAttempted;
+    }
+    constructor(ctx, config) {
+        this.#ctx = ctx;
+        this.#config = config;
+        debug('creating authenticator. config %O', this.#config);
+    }
+    /**
+     * Returns an instance of a known guard. Guards instances are
+     * cached during the lifecycle of an HTTP request.
+     */
+    use(guard) {
+        const guardToUse = guard || this.#config.default;
+        /**
+         * Use cached copy if exists
+         */
+        const cachedGuard = this.#guardsCache[guardToUse];
+        if (cachedGuard) {
+            debug('using guard from cache. name: "%s"', guardToUse);
+            return cachedGuard;
+        }
+        const guardFactory = this.#config.guards[guardToUse];
+        /**
+         * Construct guard and cache it
+         */
+        debug('creating guard. name: "%s"', guardToUse);
+        const guardInstance = guardFactory(this.#ctx);
+        this.#guardsCache[guardToUse] = guardInstance;
+        return guardInstance;
+    }
+    /**
+     * 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, "AuthenticationException" will be raised.
+     */
+    async authenticateUsing(guards, options) {
+        const guardsToUse = guards || [this.defaultGuard];
+        let lastUsedGuardDriver;
+        for (let guardName of guardsToUse) {
+            debug('attempting to authenticate using guard "%s"', guardName);
+            const guard = this.use(guardName);
+            lastUsedGuardDriver = guard.driverName;
+            if (await guard.check()) {
+                this.#authenticatedViaGuard = guardName;
+                return true;
+            }
+        }
+        throw new AuthenticationException('Unauthorized access', {
+            code: 'E_UNAUTHORIZED_ACCESS',
+            guardDriverName: lastUsedGuardDriver,
+            redirectTo: options?.redirectTo,
+        });
+    }
+}

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

@@ -0,0 +1,3 @@
+/// <reference types="node" resolution-mode="require"/>
+declare const _default: import("util").DebugLogger;
+export default _default;

package/build/{adonis-typings/container.js → src/auth/debug.js}

@@ -1,8 +1,10 @@
 /*
  * @adonisjs/auth
  *
- * (c) Harminder Virk <virk@adonisjs.com>
+ * (c) AdonisJS
  *
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+import { debuglog } from 'node:util';
+export default debuglog('adonisjs:auth');

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

@@ -0,0 +1,30 @@
+import type { ConfigProvider } from '@adonisjs/core/types';
+import type { GuardConfigProvider, GuardFactory } from './types.js';
+import type { LucidUserProvider, DatabaseUserProvider } from './user_providers/main.js';
+import type { LucidAuthenticatable, LucidUserProviderOptions, DatabaseUserProviderOptions } from '../core/types.js';
+/**
+ * Config resolved by the "defineConfig" method
+ */
+export type ResolvedAuthConfig<KnownGuards extends Record<string, GuardFactory | GuardConfigProvider<GuardFactory>>> = {
+    default: keyof KnownGuards;
+    guards: {
+        [K in keyof KnownGuards]: KnownGuards[K] extends GuardConfigProvider<infer A> ? A : KnownGuards[K];
+    };
+};
+/**
+ * Define configuration for the auth package. The function returns
+ * a config provider that is invoked inside the auth service
+ * provider
+ */
+export declare function defineConfig<KnownGuards extends Record<string, GuardFactory | GuardConfigProvider<GuardFactory>>>(config: {
+    default: keyof KnownGuards;
+    guards: KnownGuards;
+}): ConfigProvider<ResolvedAuthConfig<KnownGuards>>;
+/**
+ * Providers helper to configure user providers for
+ * finding users for authentication
+ */
+export declare const providers: {
+    db: <RealUser extends Record<string, any>>(config: DatabaseUserProviderOptions<RealUser>) => ConfigProvider<DatabaseUserProvider<RealUser>>;
+    lucid: <RealUser extends LucidAuthenticatable>(config: LucidUserProviderOptions<RealUser>) => ConfigProvider<LucidUserProvider<RealUser>>;
+};

package/build/src/auth/define_config.js

@@ -0,0 +1,54 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+/// <reference types="@adonisjs/lucid/database_provider" />
+import { configProvider } from '@adonisjs/core';
+/**
+ * Define configuration for the auth package. The function returns
+ * a config provider that is invoked inside the auth service
+ * provider
+ */
+export function defineConfig(config) {
+    return configProvider.create(async (app) => {
+        const guardsList = Object.keys(config.guards);
+        const guards = {};
+        for (let guardName of guardsList) {
+            const guard = config.guards[guardName];
+            if (typeof guard === 'function') {
+                guards[guardName] = guard;
+            }
+            else {
+                guards[guardName] = await guard.resolver(guardName, app);
+            }
+        }
+        return {
+            default: config.default,
+            guards: guards,
+        };
+    });
+}
+/**
+ * Providers helper to configure user providers for
+ * finding users for authentication
+ */
+export const providers = {
+    db(config) {
+        return configProvider.create(async (app) => {
+            const db = await app.container.make('lucid.db');
+            const hasher = await app.container.make('hash');
+            const { DatabaseUserProvider } = await import('./user_providers/main.js');
+            return new DatabaseUserProvider(db, hasher.use(), config);
+        });
+    },
+    lucid(config) {
+        return configProvider.create(async () => {
+            const { LucidUserProvider } = await import('./user_providers/main.js');
+            return new LucidUserProvider(config);
+        });
+    },
+};

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

@@ -0,0 +1,82 @@
+import { Exception } from '@poppinss/utils';
+import { HttpContext } from '@adonisjs/core/http';
+/**
+ * Authentication exception is raised when an attempt is
+ * made to authenticate an HTTP request
+ */
+export declare class AuthenticationException extends Exception {
+    /**
+     * Raises authentication exception when session guard
+     * is unable to authenticate the request
+     */
+    static E_INVALID_AUTH_SESSION(): AuthenticationException;
+    guardDriverName: string;
+    redirectTo?: string;
+    identifier: string;
+    constructor(message: string, options: ErrorOptions & {
+        guardDriverName: string;
+        redirectTo?: string;
+        code?: string;
+        status?: number;
+    });
+    /**
+     * Returns the message to be sent in the HTTP response.
+     * Feel free to override this method and return a custom
+     * response.
+     */
+    getResponseMessage(error: AuthenticationException, ctx: HttpContext): string;
+    /**
+     * 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: Record<string, (message: string, error: AuthenticationException, ctx: HttpContext) => Promise<void> | void>;
+    /**
+     * Self handles the auth exception and converts it to an
+     * HTTP response
+     */
+    handle(error: AuthenticationException, ctx: HttpContext): Promise<void>;
+}
+/**
+ * Invalid credentials exception is raised when unable
+ * to verify user credentials during login
+ */
+export declare class InvalidCredentialsException extends Exception {
+    static message: string;
+    static code: string;
+    static E_INVALID_CREDENTIALS(guardDriverName: string): InvalidCredentialsException;
+    guardDriverName: string;
+    identifier: string;
+    constructor(message: string, options: ErrorOptions & {
+        guardDriverName: string;
+        code?: string;
+        status?: number;
+    });
+    /**
+     * Returns the message to be sent in the HTTP response.
+     * Feel free to override this method and return a custom
+     * response.
+     */
+    getResponseMessage(error: InvalidCredentialsException, ctx: HttpContext): string;
+    /**
+     * 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: Record<string, (message: string, error: InvalidCredentialsException, ctx: HttpContext) => Promise<void> | void>;
+    /**
+     * Self handles the auth exception and converts it to an
+     * HTTP response
+     */
+    handle(error: InvalidCredentialsException, ctx: HttpContext): Promise<void>;
+}

package/build/src/auth/errors.js

@@ -0,0 +1,181 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { Exception } from '@poppinss/utils';
+/**
+ * Authentication exception is raised when an attempt is
+ * made to authenticate an HTTP request
+ */
+export class AuthenticationException extends Exception {
+    /**
+     * 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',
+        });
+    }
+    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.flash({ errors: { [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;
+            }
+        },
+    };
+    /**
+     * 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);
+    }
+}
+/**
+ * Invalid credentials exception is raised when unable
+ * to verify user credentials during login
+ */
+export class InvalidCredentialsException extends Exception {
+    static message = 'Invalid credentials';
+    static code = 'E_INVALID_CREDENTIALS';
+    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.flash({ errors: { [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/auth_middleware.d.ts

@@ -0,0 +1,13 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { NextFn } from '@adonisjs/core/types/http';
+import type { Authenticators } from '@adonisjs/auth/types';
+/**
+ * Options accepted by the middleware options
+ */
+export type AuthMiddlewareOptions = {
+    guards?: (keyof Authenticators)[];
+    redirectTo?: string;
+};
+export default class AuthMiddleware {
+    handle(ctx: HttpContext, next: NextFn, options?: AuthMiddlewareOptions): Promise<any>;
+}

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

@@ -0,0 +1,6 @@
+export default class AuthMiddleware {
+    async handle(ctx, next, options = {}) {
+        await ctx.auth.authenticateUsing(options.guards, options);
+        return next();
+    }
+}

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/symbols.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A symbol to identify the type of the real user for a given
+ * user provider
+ */
+export declare const PROVIDER_REAL_USER: unique symbol;
+/**
+ * A symbol to identify the type for the events emitted by a guard
+ */
+export declare const GUARD_KNOWN_EVENTS: unique symbol;

package/build/src/auth/symbols.js

@@ -0,0 +1,17 @@
+/*
+ * @adonisjs/lucid
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+/**
+ * A symbol to identify the type of the real user for a given
+ * user provider
+ */
+export const PROVIDER_REAL_USER = Symbol.for('PROVIDER_REAL_USER');
+/**
+ * A symbol to identify the type for the events emitted by a guard
+ */
+export const GUARD_KNOWN_EVENTS = Symbol.for('GUARD_KNOWN_EVENTS');

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

@@ -0,0 +1,75 @@
+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';
+/**
+ * A set of properties a guard must implement.
+ */
+export interface GuardContract<User> {
+    /**
+     * Reference to the currently authenticated user
+     */
+    user?: 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>;
+    /**
+     * 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;
+}
+/**
+ * The authenticator guard factory method is called by the
+ * Authenticator class to create an instance of a specific
+ * guard during an HTTP request
+ */
+export type GuardFactory = (ctx: HttpContext) => GuardContract<unknown>;
+/**
+ * Authenticators are inferred inside the user application
+ * from the config file
+ */
+export interface Authenticators {
+}
+/**
+ * Infer authenticators from the auth config
+ */
+export type InferAuthenticators<Config extends ConfigProvider<{
+    default: unknown;
+    guards: unknown;
+}>> = Awaited<ReturnType<Config['resolver']>>['guards'];
+/**
+ * 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 Record<string, GuardFactory> ? Authenticators : never> {
+}
+/**
+ * Config provider for exporting guard
+ */
+export type GuardConfigProvider<Guard extends GuardFactory> = {
+    resolver: (name: string, app: ApplicationService) => Promise<Guard>;
+};

package/build/{adonis-typings/context.js → src/auth/types.js}

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