@adonisjs/auth 10.0.0-next.6 → 10.1.0

package/build/auth_manager-Cp_ofh4p.js

@@ -0,0 +1,384 @@
+import { n as E_UNAUTHORIZED_ACCESS } from "./errors-eDV8ejO0.js";
+import { t as debug_default } from "./debug-CrTUB4zl.js";
+import { RuntimeException } from "@adonisjs/core/exceptions";
+import { HttpContextFactory } from "@adonisjs/core/factories/http";
+//#region src/authenticator.ts
+/**
+* Authenticator is used to authenticate incoming HTTP requests
+* using one or more known guards.
+*/
+var Authenticator = class {
+	/**
+	* Registered guards
+	*/
+	#config;
+	/**
+	* Cache of guards created during the HTTP request
+	*/
+	#guardsCache = {};
+	/**
+	* Last guard that was used to perform the authentication via
+	* the "authenticateUsing" method.
+	*
+	* @note
+	* Reset on every call made to "authenticate", "check" and
+	* "authenticateUsing" method.
+	*/
+	#authenticationAttemptedViaGuard;
+	/**
+	* Name of the guard using which the request has
+	* been authenticated successfully.
+	*
+	* @note
+	* Reset on every call made to "authenticate", "check" and
+	* "authenticateUsing" method.
+	*/
+	#authenticatedViaGuard;
+	/**
+	* Reference to HTTP context
+	*/
+	#ctx;
+	/**
+	* Name of the default guard configured in the auth configuration
+	*
+	* @example
+	* const defaultGuard = auth.defaultGuard
+	* console.log(defaultGuard) // 'web'
+	*/
+	get defaultGuard() {
+		return this.#config.default;
+	}
+	/**
+	* Reference to the guard using which the current
+	* request has been authenticated. Returns undefined if
+	* authentication has not been attempted or failed.
+	*
+	* @example
+	* await auth.authenticate()
+	* console.log(auth.authenticatedViaGuard) // 'web'
+	*/
+	get authenticatedViaGuard() {
+		return this.#authenticatedViaGuard;
+	}
+	/**
+	* A boolean to know if the current request has been authenticated. The
+	* property returns false when "authenticate" or "authenticateUsing"
+	* methods are not used.
+	*
+	* @example
+	* await auth.authenticate()
+	* console.log(auth.isAuthenticated) // true
+	*/
+	get isAuthenticated() {
+		if (!this.#authenticationAttemptedViaGuard) return false;
+		return this.use(this.#authenticationAttemptedViaGuard).isAuthenticated;
+	}
+	/**
+	* Reference to the currently authenticated user. The property returns
+	* undefined when "authenticate" or "authenticateUsing" methods are
+	* not used.
+	*
+	* @example
+	* await auth.authenticate()
+	* console.log(auth.user?.email)
+	*/
+	get user() {
+		if (!this.#authenticationAttemptedViaGuard) return;
+		return this.use(this.#authenticationAttemptedViaGuard).user;
+	}
+	/**
+	* Whether or not the authentication has been attempted during
+	* the current request. The property returns false when the
+	* "authenticate" or "authenticateUsing" methods are not
+	* used.
+	*
+	* @example
+	* await auth.check()
+	* console.log(auth.authenticationAttempted) // true
+	*/
+	get authenticationAttempted() {
+		if (!this.#authenticationAttemptedViaGuard) return false;
+		return this.use(this.#authenticationAttemptedViaGuard).authenticationAttempted;
+	}
+	/**
+	* Creates a new Authenticator instance
+	*
+	* @param ctx - The HTTP context for the current request
+	* @param config - Configuration object containing default guard and available guards
+	*
+	* @example
+	* const authenticator = new Authenticator(ctx, {
+	*   default: 'web',
+	*   guards: { web: sessionGuard }
+	* })
+	*/
+	constructor(ctx, config) {
+		this.#ctx = ctx;
+		this.#config = config;
+		debug_default("creating authenticator. config %O", this.#config);
+	}
+	/**
+	* Returns an instance of the logged-in user or throws an exception
+	*
+	* @throws {RuntimeException} When authentication has not been attempted
+	*
+	* @example
+	* const user = auth.getUserOrFail()
+	* console.log(user.id)
+	*/
+	getUserOrFail() {
+		if (!this.#authenticationAttemptedViaGuard) throw new RuntimeException("Cannot access authenticated user. Please call \"auth.authenticate\" method first.");
+		return this.use(this.#authenticationAttemptedViaGuard).getUserOrFail();
+	}
+	/**
+	* Returns an instance of a known guard. Guards instances are
+	* cached during the lifecycle of an HTTP request.
+	*
+	* @param guard - Optional guard name. Uses default guard if not provided
+	*
+	* @example
+	* const sessionGuard = auth.use('session')
+	* const defaultGuard = auth.use()
+	*/
+	use(guard) {
+		const guardToUse = guard || this.#config.default;
+		/**
+		* Use cached copy if exists
+		*/
+		const cachedGuard = this.#guardsCache[guardToUse];
+		if (cachedGuard) {
+			debug_default("authenticator: using guard from cache. name: \"%s\"", guardToUse);
+			return cachedGuard;
+		}
+		const guardFactory = this.#config.guards[guardToUse];
+		/**
+		* Construct guard and cache it
+		*/
+		debug_default("authenticator: creating guard. name: \"%s\"", guardToUse);
+		const guardInstance = guardFactory(this.#ctx);
+		this.#guardsCache[guardToUse] = guardInstance;
+		return guardInstance;
+	}
+	/**
+	* Authenticate current request using the default guard. Calling this
+	* method multiple times triggers multiple authentication with the
+	* guard.
+	*
+	* @throws {E_UNAUTHORIZED_ACCESS} When authentication fails
+	*
+	* @example
+	* const user = await auth.authenticate()
+	* console.log('Authenticated user:', user.email)
+	*/
+	async authenticate() {
+		await this.authenticateUsing();
+		return this.getUserOrFail();
+	}
+	/**
+	* Silently attempt to authenticate the request using the default
+	* guard. Calling this method multiple times triggers multiple
+	* authentication with the guard.
+	*
+	* @example
+	* const isAuthenticated = await auth.check()
+	* if (isAuthenticated) {
+	*   console.log('User is authenticated')
+	* }
+	*/
+	async check() {
+		this.#authenticationAttemptedViaGuard = this.defaultGuard;
+		const isAuthenticated = await this.use().check();
+		if (isAuthenticated) this.#authenticatedViaGuard = this.defaultGuard;
+		return isAuthenticated;
+	}
+	/**
+	* 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, "E_UNAUTHORIZED_ACCESS" will be raised.
+	*
+	* @param guards - Array of guard names to try for authentication
+	* @param options - Options object with optional loginRoute for redirects
+	*
+	* @throws {E_UNAUTHORIZED_ACCESS} When none of the guards can authenticate
+	*
+	* @example
+	* const user = await auth.authenticateUsing(['session', 'api'])
+	* const userWithRedirect = await auth.authenticateUsing(['web'], { loginRoute: '/login' })
+	*/
+	async authenticateUsing(guards, options) {
+		const guardsToUse = guards || [this.defaultGuard];
+		let lastUsedDriver;
+		for (let guardName of guardsToUse) {
+			debug_default("attempting to authenticate using guard \"%s\"", guardName);
+			this.#authenticationAttemptedViaGuard = guardName;
+			const guard = this.use(guardName);
+			lastUsedDriver = guard.driverName;
+			if (await guard.check()) {
+				this.#authenticatedViaGuard = guardName;
+				return this.getUserOrFail();
+			}
+		}
+		throw new E_UNAUTHORIZED_ACCESS("Unauthorized access", {
+			guardDriverName: lastUsedDriver,
+			redirectTo: options?.loginRoute
+		});
+	}
+	/**
+	* Silently attempt to authenticate the request using all of the mentioned guards
+	* or the default guard. Calling this method multiple times triggers multiple
+	* authentication with the guard.
+	*
+	* @param guards - Array of guard names to check. Defaults to default guard
+	*
+	* @example
+	* const isAuthenticated = await auth.checkUsing(['session', 'api'])
+	* if (isAuthenticated) {
+	*   const user = auth.user
+	* }
+	*/
+	async checkUsing(guards = [this.defaultGuard]) {
+		for (const name of guards) {
+			this.#authenticationAttemptedViaGuard = name;
+			if (await this.use(name).check()) {
+				this.#authenticatedViaGuard = name;
+				return true;
+			}
+		}
+		return false;
+	}
+};
+//#endregion
+//#region src/authenticator_client.ts
+/**
+* Authenticator client is used to create guard instances for testing.
+* It passes a fake HTTPContext to the guards, so make sure to not
+* call server side APIs that might be relying on a real
+* HTTPContext instance.
+*/
+var AuthenticatorClient = class {
+	/**
+	* Registered guards
+	*/
+	#config;
+	/**
+	* Cache of guards
+	*/
+	#guardsCache = {};
+	/**
+	* Name of the default guard configured in the auth configuration
+	*
+	* @example
+	* const client = new AuthenticatorClient({ default: 'web', guards: {} })
+	* console.log(client.defaultGuard) // 'web'
+	*/
+	get defaultGuard() {
+		return this.#config.default;
+	}
+	/**
+	* Creates a new AuthenticatorClient instance for testing
+	*
+	* @param config - Configuration object containing default guard and available guards
+	*
+	* @example
+	* const client = new AuthenticatorClient({
+	*   default: 'web',
+	*   guards: { web: sessionGuard }
+	* })
+	*/
+	constructor(config) {
+		this.#config = config;
+		debug_default("creating authenticator client. config %O", this.#config);
+	}
+	/**
+	* Returns an instance of a known guard. Guards instances are
+	* cached during the lifecycle of an HTTP request.
+	*
+	* @param guard - Optional guard name. Uses default guard if not provided
+	*
+	* @example
+	* const sessionGuard = client.use('session')
+	* const defaultGuard = client.use()
+	*/
+	use(guard) {
+		const guardToUse = guard || this.#config.default;
+		/**
+		* Use cached copy if exists
+		*/
+		const cachedGuard = this.#guardsCache[guardToUse];
+		if (cachedGuard) {
+			debug_default("authenticator client: using guard from cache. name: \"%s\"", guardToUse);
+			return cachedGuard;
+		}
+		const guardFactory = this.#config.guards[guardToUse];
+		/**
+		* Construct guard and cache it
+		*/
+		debug_default("authenticator client: creating guard. name: \"%s\"", guardToUse);
+		const guardInstance = guardFactory(new HttpContextFactory().create());
+		this.#guardsCache[guardToUse] = guardInstance;
+		return guardInstance;
+	}
+};
+//#endregion
+//#region src/auth_manager.ts
+/**
+* Auth manager exposes the API to register and manage authentication
+* guards from the config
+*/
+var AuthManager = class {
+	/**
+	* Name of the default guard configured in the auth configuration
+	*
+	* @example
+	* const manager = new AuthManager({ default: 'web', guards: {} })
+	* console.log(manager.defaultGuard) // 'web'
+	*/
+	get defaultGuard() {
+		return this.config.default;
+	}
+	/**
+	* Creates a new AuthManager instance
+	*
+	* @param config - Configuration object containing default guard and available guards
+	*
+	* @example
+	* const manager = new AuthManager({
+	*   default: 'web',
+	*   guards: { web: sessionGuard, api: tokenGuard }
+	* })
+	*/
+	constructor(config) {
+		this.config = config;
+		this.config = config;
+	}
+	/**
+	* Create an authenticator for a given HTTP request. The authenticator
+	* is used to authenticate incoming HTTP requests
+	*
+	* @param ctx - The HTTP context for the current request
+	*
+	* @example
+	* const authenticator = manager.createAuthenticator(ctx)
+	* const user = await authenticator.authenticate()
+	*/
+	createAuthenticator(ctx) {
+		return new Authenticator(ctx, this.config);
+	}
+	/**
+	* Creates an instance of the authenticator client. The client is
+	* used to setup authentication state during testing.
+	*
+	* @example
+	* const client = manager.createAuthenticatorClient()
+	* const guard = client.use('session')
+	*/
+	createAuthenticatorClient() {
+		return new AuthenticatorClient(this.config);
+	}
+};
+//#endregion
+export { AuthenticatorClient as n, Authenticator as r, AuthManager as t };

package/build/debug-CrTUB4zl.js

@@ -0,0 +1,12 @@
+import { debuglog } from "node:util";
+//#region src/debug.ts
+/**
+* Debug logger instance for the AdonisJS auth package.
+* Set NODE_DEBUG=adonisjs:auth environment variable to enable debug logging.
+*
+* @example
+* debug('authenticating user %s', user.email)
+*/
+var debug_default = debuglog("adonisjs:auth");
+//#endregion
+export { debug_default as t };

package/build/{errors-Ns_FO2np.js → errors-eDV8ejO0.js}

@@ -1,25 +1,59 @@
-import "node:module";
 import { Exception } from "@adonisjs/core/exceptions";
+//#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
-var __exportAll = (all, symbols) => {
+var __exportAll = (all, no_symbols) => {
 	let target = {};
 	for (var name in all) __defProp(target, name, {
 		get: all[name],
 		enumerable: true
 	});
-	if (symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
 	return target;
 };
+//#endregion
+//#region src/errors.ts
 var errors_exports = /* @__PURE__ */ __exportAll({
 	E_INVALID_CREDENTIALS: () => E_INVALID_CREDENTIALS,
 	E_UNAUTHORIZED_ACCESS: () => E_UNAUTHORIZED_ACCESS
 });
+/**
+* The "E_UNAUTHORIZED_ACCESS" exception is raised when unable to
+* authenticate an incoming HTTP request.
+*
+* The "error.guardDriverName" can be used to know the driver which
+* raised the error.
+*/
 const E_UNAUTHORIZED_ACCESS = class extends Exception {
+	/**
+	* HTTP status code for unauthorized access
+	*/
 	static status = 401;
+	/**
+	* Error code identifier
+	*/
 	static code = "E_UNAUTHORIZED_ACCESS";
+	/**
+	* Endpoint to redirect to. Only used by "session" driver
+	* renderer
+	*/
 	redirectTo;
+	/**
+	* Translation identifier. Can be customized
+	*/
 	identifier = "errors.E_UNAUTHORIZED_ACCESS";
+	/**
+	* The guard name reference that raised the exception. It allows
+	* us to customize the logic of handling the exception.
+	*/
 	guardDriverName;
+	/**
+	* A collection of 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([
@@ -31,8 +65,11 @@ const E_UNAUTHORIZED_ACCESS = class extends Exception {
 				case null:
 					ctx.session.flashExcept(["_csrf"]);
 					ctx.session.flash("error", message);
+					/**
+					* The "flashErrors" call must be removed in the future
+					*/
 					ctx.session.flashErrors({ [error.code]: message });
-					ctx.response.redirect(error.redirectTo || "/", true);
+					ctx.response.redirect().withIntendedUrl().withQs().toPath(error.redirectTo || "/");
 					break;
 				case "json":
 					ctx.response.status(error.status).send({ errors: [{ message }] });
@@ -70,15 +107,49 @@ const E_UNAUTHORIZED_ACCESS = class extends Exception {
 			}
 		}
 	};
+	/**
+	* Returns the message to be sent in the HTTP response.
+	* Feel free to override this method and return a custom
+	* response.
+	*
+	* @param error - The error instance
+	* @param ctx - The HTTP context
+	*
+	* @example
+	* const message = error.getResponseMessage(error, ctx)
+	* console.log('Error message:', message)
+	*/
 	getResponseMessage(error, ctx) {
 		if ("i18n" in ctx) return ctx.i18n.t(error.identifier, {}, error.message);
 		return error.message;
 	}
+	/**
+	* Creates a new E_UNAUTHORIZED_ACCESS exception
+	*
+	* @param message - The error message
+	* @param options - Options including redirectTo and guardDriverName
+	*
+	* @example
+	* throw new E_UNAUTHORIZED_ACCESS('Access denied', {
+	*   guardDriverName: 'session',
+	*   redirectTo: '/login'
+	* })
+	*/
 	constructor(message, options) {
 		super(message, {});
 		this.guardDriverName = options.guardDriverName;
 		this.redirectTo = options.redirectTo;
 	}
+	/**
+	* Converts exception to an HTTP response
+	*
+	* @param error - The error instance
+	* @param ctx - The HTTP context
+	*
+	* @example
+	* // This method is called automatically by AdonisJS
+	* await error.handle(error, ctx)
+	*/
 	async handle(error, ctx) {
 		const renderer = this.renderers[this.guardDriverName];
 		const message = error.getResponseMessage(error, ctx);
@@ -86,14 +157,51 @@ const E_UNAUTHORIZED_ACCESS = class extends Exception {
 		return renderer(message, error, ctx);
 	}
 };
+/**
+* Exception is raised when user credentials are invalid
+*
+* @example
+* throw new E_INVALID_CREDENTIALS('Invalid email or password')
+*/
 const E_INVALID_CREDENTIALS = class extends Exception {
+	/**
+	* HTTP status code for invalid credentials
+	*/
 	static status = 400;
+	/**
+	* Error code identifier
+	*/
 	static code = "E_INVALID_CREDENTIALS";
+	/**
+	* Translation identifier. Can be customized
+	*/
 	identifier = "errors.E_INVALID_CREDENTIALS";
+	/**
+	* Returns the message to be sent in the HTTP response.
+	* Feel free to override this method and return a custom
+	* response.
+	*
+	* @param error - The error instance
+	* @param ctx - The HTTP context
+	*
+	* @example
+	* const message = error.getResponseMessage(error, ctx)
+	* console.log('Error message:', message)
+	*/
 	getResponseMessage(error, ctx) {
 		if ("i18n" in ctx) return ctx.i18n.t(error.identifier, {}, error.message);
 		return error.message;
 	}
+	/**
+	* Converts exception to an HTTP response
+	*
+	* @param error - The error instance
+	* @param ctx - The HTTP context
+	*
+	* @example
+	* // This method is called automatically by AdonisJS
+	* await error.handle(error, ctx)
+	*/
 	async handle(error, ctx) {
 		const message = this.getResponseMessage(error, ctx);
 		switch (ctx.request.accepts([
@@ -111,6 +219,9 @@ const E_INVALID_CREDENTIALS = class extends Exception {
 						"password_confirmation"
 					]);
 					ctx.session.flash("error", message);
+					/**
+					* The "flashErrors" call must be removed in the future
+					*/
 					ctx.session.flashErrors({ [error.code]: message });
 					ctx.response.redirect("back", true);
 				} else ctx.response.status(error.status).send(message);
@@ -127,4 +238,5 @@ const E_INVALID_CREDENTIALS = class extends Exception {
 		}
 	}
 };
+//#endregion
 export { __exportAll as i, E_UNAUTHORIZED_ACCESS as n, errors_exports as r, E_INVALID_CREDENTIALS as t };

package/build/index.js

@@ -1,12 +1,19 @@
-import { r as errors_exports } from "./errors-Ns_FO2np.js";
-import { t as symbols_exports } from "./symbols-BwcLqNln.js";
-import "./debug-Ckko95-M.js";
-import { n as AuthenticatorClient, r as Authenticator, t as AuthManager } from "./auth_manager-CJvMGOzX.js";
+import { r as errors_exports } from "./errors-eDV8ejO0.js";
+import { t as symbols_exports } from "./symbols-C5QEqFvJ.js";
+import { n as AuthenticatorClient, r as Authenticator, t as AuthManager } from "./auth_manager-Cp_ofh4p.js";
 import { presetAuth } from "@adonisjs/presets/auth";
 import { configProvider } from "@adonisjs/core";
+//#region configure.ts
+/**
+* Configures the auth package
+*/
 async function configure(command) {
 	const codemods = await command.createCodemods();
 	let guard = command.parsedFlags.guard;
+	/**
+	* Prompts user to select a guard when not mentioned via
+	* the CLI
+	*/
 	if (guard === void 0) guard = await command.prompt.choice("Select the auth guard you want to use", [
 		{
 			name: "session",
@@ -23,6 +30,10 @@ async function configure(command) {
 	], { validate(value) {
 		return !!value;
 	} });
+	/**
+	* Ensure selected or guard defined via the CLI flag is
+	* valid
+	*/
 	if (![
 		"session",
 		"access_tokens",
@@ -37,6 +48,31 @@ async function configure(command) {
 		userProvider: "lucid"
 	});
 }
+//#endregion
+//#region src/define_config.ts
+/**
+* Define configuration for the auth package. The function returns
+* a config provider that is invoked inside the auth service
+* provider
+*
+* @param config - Configuration object with default guard and available guards
+*
+* @example
+* import { defineConfig } from '@adonisjs/auth'
+* import { sessionGuard, sessionUserProvider } from '@adonisjs/auth/session'
+*
+* const authConfig = defineConfig({
+*   default: 'web',
+*   guards: {
+*     web: sessionGuard({
+*       useRememberMeTokens: false,
+*       provider: sessionUserProvider({
+*         model: () => import('#models/user')
+*       })
+*     })
+*   }
+* })
+*/
 function defineConfig(config) {
 	return configProvider.create(async (app) => {
 		const guardsList = Object.keys(config.guards);
@@ -52,6 +88,8 @@ function defineConfig(config) {
 		};
 	});
 }
+//#endregion
+//#region index.ts
 function isModuleInstalled(moduleName) {
 	try {
 		import.meta.resolve(moduleName);
@@ -60,9 +98,13 @@ function isModuleInstalled(moduleName) {
 		return false;
 	}
 }
+/**
+* @deprecated Import `withAuthFinder` from `@adonisjs/auth/mixins/lucid` instead
+*/
 let withAuthFinder;
 if (isModuleInstalled("@adonisjs/lucid")) {
 	const { withAuthFinder: withAuthFinderFn } = await import("./src/mixins/lucid.js");
 	withAuthFinder = withAuthFinderFn;
 }
+//#endregion
 export { AuthManager, Authenticator, AuthenticatorClient, configure, defineConfig, errors_exports as errors, symbols_exports as symbols, withAuthFinder };