@adonisjs/auth 10.0.0 → 10.1.0

package/build/providers/auth_provider.js

@@ -1,12 +1,32 @@
-import "../errors-sGy-K8pd.js";
-import "../debug-Ckko95-M.js";
-import { t as AuthManager } from "../auth_manager-hJTiBA2V.js";
+import { t as AuthManager } from "../auth_manager-Cp_ofh4p.js";
 import { RuntimeException } from "@adonisjs/core/exceptions";
 import { configProvider } from "@adonisjs/core";
+//#region providers/auth_provider.ts
+/**
+* The AuthProvider service provider registers the auth manager
+* with the IoC container as a singleton
+*
+* @example
+* // The auth manager is automatically registered and can be injected
+* container.use('auth.manager')
+*/
 var AuthProvider = class {
+	/**
+	* Creates a new AuthProvider instance
+	*
+	* @param app - The application service instance
+	*/
 	constructor(app) {
 		this.app = app;
 	}
+	/**
+	* Registers the auth manager as a singleton service
+	* in the IoC container
+	*
+	* @example
+	* // This method is called automatically by AdonisJS
+	* // The auth manager becomes available as 'auth.manager'
+	*/
 	register() {
 		this.app.container.singleton("auth.manager", async () => {
 			const authConfigProvider = this.app.config.get("auth");
@@ -16,4 +36,5 @@ var AuthProvider = class {
 		});
 	}
 };
+//#endregion
 export { AuthProvider as default };

package/build/services/auth.js

@@ -1,6 +1,11 @@
 import app from "@adonisjs/core/services/app";
+//#region services/auth.ts
 let auth;
+/**
+* Returns a singleton instance of the Auth manager class
+*/
 await app.booted(async () => {
 	auth = await app.container.make("auth.manager");
 });
+//#endregion
 export { auth as default };

package/build/src/middleware/initialize_auth_middleware.js

@@ -1,8 +1,37 @@
+//#region src/middleware/initialize_auth_middleware.ts
+/**
+* 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.
+*
+* @example
+* router.use([() => import('#middleware/initialize_auth_middleware')])
+*/
 var InitializeAuthMiddleware = class {
+	/**
+	* Handle the HTTP request by initializing the authenticator
+	*
+	* @param ctx - The HTTP context
+	* @param next - The next function to call in the middleware chain
+	*
+	* @example
+	* // This middleware runs automatically when registered
+	* // It adds ctx.auth to every HTTP request
+	*/
 	async handle(ctx, next) {
+		/**
+		* Initialize the authenticator for the current HTTP
+		* request
+		*/
 		ctx.auth = (await ctx.containerResolver.make("auth.manager")).createAuthenticator(ctx);
+		/**
+		* Sharing authenticator with templates
+		*/
 		if ("view" in ctx) ctx.view.share({ auth: ctx.auth });
 		return next();
 	}
 };
+//#endregion
 export { InitializeAuthMiddleware as default };

package/build/src/mixins/lucid.js

@@ -1,12 +1,39 @@
-import { t as E_INVALID_CREDENTIALS } from "../../errors-sGy-K8pd.js";
+import { t as E_INVALID_CREDENTIALS } from "../../errors-eDV8ejO0.js";
 import { RuntimeException } from "@adonisjs/core/exceptions";
 import { beforeSave } from "@adonisjs/lucid/orm";
+//#region \0@oxc-project+runtime@0.122.0/helpers/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
 	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
 	return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
+//#endregion
+//#region src/mixins/lucid.ts
+/**
+* Mixing to add user lookup and password verification methods
+* on a model.
+*
+* Under the hood, this mixin defines following methods and hooks
+*
+* - beforeSave hook to hash user password
+* - findForAuth method to find a user during authentication
+* - verifyCredentials method to verify user credentials and prevent
+*   timing attacks.
+*
+* @param hash - Function that returns a Hash instance for password hashing
+* @param options - Configuration options with uids and password column name
+*
+* @example
+* import { withAuthFinder } from '@adonisjs/auth/mixins/lucid'
+*
+* class User extends withAuthFinder(hash, {
+*   uids: ['email', 'username'],
+*   passwordColumnName: 'password'
+* })(BaseModel) {
+*   // User model implementation
+* }
+*/
 function withAuthFinder(hash, options) {
 	let normalizedOptions = {
 		uids: ["email"],
@@ -16,15 +43,54 @@ function withAuthFinder(hash, options) {
 	let hashFactory = typeof hash === "function" ? hash : () => hash.use();
 	return function(superclass) {
 		class UserWithUserFinder extends superclass {
+			/**
+			* Hook to hash user password when creating or updating
+			* the user model.
+			*
+			* @param user - The user instance being saved
+			*
+			* @example
+			* // This hook runs automatically before saving
+			* const user = new User()
+			* user.password = 'plaintext'
+			* await user.save() // password will be hashed automatically
+			*/
 			static async hashPassword(user) {
 				if (user.$dirty[normalizedOptions.passwordColumnName]) user[normalizedOptions.passwordColumnName] = await hashFactory().make(user[normalizedOptions.passwordColumnName]);
 			}
+			/**
+			* Finds the user for authentication via "verifyCredentials".
+			* Feel free to override this method to customize the user
+			* lookup behavior.
+			*
+			* @param uids - Array of column names to search in
+			* @param value - The value to search for
+			*
+			* @example
+			* const user = await User.findForAuth(['email', 'username'], 'john@example.com')
+			*/
 			static findForAuth(uids, value) {
 				const query = this.query();
 				uids.forEach((uid) => query.orWhere(uid, value));
 				return query.limit(1).first();
 			}
+			/**
+			* Find a user by uid and verify their password. This method is
+			* safe from timing attacks.
+			*
+			* @param uid - The user identifier (email, username, etc.)
+			* @param password - The plain text password to verify
+			*
+			* @throws {E_INVALID_CREDENTIALS} When credentials are invalid
+			*
+			* @example
+			* const user = await User.verifyCredentials('john@example.com', 'password123')
+			* console.log('Authenticated user:', user.email)
+			*/
 			static async verifyCredentials(uid, password) {
+				/**
+				* Fail when uid or the password are missing
+				*/
 				if (!uid || !password) throw new E_INVALID_CREDENTIALS("Invalid user credentials");
 				const user = await this.findForAuth(normalizedOptions.uids, uid);
 				if (!user) {
@@ -34,11 +100,37 @@ function withAuthFinder(hash, options) {
 				if (await user.verifyPassword(password)) return user;
 				throw new E_INVALID_CREDENTIALS("Invalid user credentials");
 			}
+			/**
+			* Verifies the plain password against the user's password
+			* hash
+			*
+			* @param plainPassword - The plain text password to verify
+			*
+			* @throws {RuntimeException} When password column value is undefined or null
+			*
+			* @example
+			* const isValid = await user.verifyPassword('password123')
+			* if (isValid) {
+			*   console.log('Password is correct')
+			* }
+			*/
 			verifyPassword(plainPassword) {
 				const passwordHash = this[normalizedOptions.passwordColumnName];
 				if (!passwordHash) throw new RuntimeException(`Cannot verify password. The value for "${normalizedOptions.passwordColumnName}" column is undefined or null`);
 				return hashFactory().verify(passwordHash, plainPassword);
 			}
+			/**
+			* Validates a plain password against the user's stored password hash.
+			* Throws a validation error if the password doesn't match.
+			*
+			* @param plainPassword - The plain text password to validate
+			* @param passwordFieldName - Optional field name for the error message (defaults to 'currentPassword')
+			*
+			* @throws {ValidationError} When the password is incorrect
+			*
+			* @example
+			* await user.validatePassword('oldPassword123', 'currentPassword')
+			*/
 			async validatePassword(plainPassword, passwordFieldName) {
 				if (!await this.verifyPassword(plainPassword)) {
 					const error = /* @__PURE__ */ new Error("Validation Error");
@@ -57,4 +149,5 @@ function withAuthFinder(hash, options) {
 		return UserWithUserFinder;
 	};
 }
+//#endregion
 export { withAuthFinder };

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

@@ -1,8 +1,26 @@
-import { t as debug_default } from "../../../debug-Ckko95-M.js";
+import { t as debug_default } from "../../../debug-CrTUB4zl.js";
 import { ApiClient, ApiRequest } from "@japa/api-client";
+//#region src/plugins/japa/api_client.ts
+/**
+* Auth API client to authenticate users when making
+* HTTP requests using the Japa API client
+*
+* @param app - The AdonisJS application service instance
+*
+* @example
+* import { authApiClient } from '@adonisjs/auth/plugins/japa/api_client'
+*
+* export const plugins: PluginFn[] = [
+*   authApiClient(app)
+* ]
+*/
 const authApiClient = (app) => {
 	const pluginFn = function() {
 		debug_default("installing auth api client plugin");
+		/**
+		* Login a user using the default authentication guard
+		* when making an API call
+		*/
 		ApiRequest.macro("loginAs", function(user, ...args) {
 			this.authData = {
 				guard: "__default__",
@@ -10,6 +28,9 @@ const authApiClient = (app) => {
 			};
 			return this;
 		});
+		/**
+		* Define the authentication guard for login
+		*/
 		ApiRequest.macro("withGuard", function(guard) {
 			return { loginAs: (...args) => {
 				this.authData = {
@@ -19,6 +40,9 @@ const authApiClient = (app) => {
 				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"];
@@ -42,4 +66,5 @@ const authApiClient = (app) => {
 	};
 	return pluginFn;
 };
+//#endregion
 export { authApiClient };

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

@@ -1,11 +1,29 @@
-import { t as debug_default } from "../../../debug-Ckko95-M.js";
+import { t as debug_default } from "../../../debug-CrTUB4zl.js";
 import { RuntimeException } from "@adonisjs/core/exceptions";
 import { decoratorsCollection } from "@japa/browser-client";
+//#region src/plugins/japa/browser_client.ts
+/**
+* Browser API client to authenticate users when making
+* HTTP requests using the Japa Browser client.
+*
+* @param app - The AdonisJS application service instance
+*
+* @example
+* import { authBrowserClient } from '@adonisjs/auth/plugins/japa/browser_client'
+*
+* export const plugins: PluginFn[] = [
+*   authBrowserClient(app)
+* ]
+*/
 const authBrowserClient = (app) => {
 	const pluginFn = async function() {
 		debug_default("installing auth browser client plugin");
 		const auth = await app.container.make("auth.manager");
 		decoratorsCollection.register({ context(context) {
+			/**
+			* Define the authentication guard for login and perform
+			* login
+			*/
 			context.withGuard = function(guardName) {
 				return { async loginAs(...args) {
 					const guard = auth.createAuthenticatorClient().use(guardName);
@@ -24,6 +42,10 @@ const authBrowserClient = (app) => {
 					}
 				} };
 			};
+			/**
+			* Login a user using the default authentication guard when
+			* using the browser context to make page visits
+			*/
 			context.loginAs = async function(user, ...args) {
 				const guard = auth.createAuthenticatorClient().use();
 				const requestData = await guard.authenticateAsClient(user, ...args);
@@ -44,4 +66,5 @@ const authBrowserClient = (app) => {
 	};
 	return pluginFn;
 };
+//#endregion
 export { authBrowserClient };

package/build/{symbols-BQLDWwuQ.js → symbols-C5QEqFvJ.js}

@@ -1,8 +1,17 @@
-import { i as __exportAll } from "./errors-sGy-K8pd.js";
+import { i as __exportAll } from "./errors-eDV8ejO0.js";
+//#region src/symbols.ts
 var symbols_exports = /* @__PURE__ */ __exportAll({
 	GUARD_KNOWN_EVENTS: () => GUARD_KNOWN_EVENTS,
 	PROVIDER_REAL_USER: () => PROVIDER_REAL_USER
 });
+/**
+* A symbol to identify the type of the real user for a given
+* user provider
+*/
 const PROVIDER_REAL_USER = Symbol.for("PROVIDER_REAL_USER");
+/**
+* A symbol to identify the type for the events emitted by a guard
+*/
 const GUARD_KNOWN_EVENTS = Symbol.for("GUARD_KNOWN_EVENTS");
+//#endregion
 export { symbols_exports as t };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adonisjs/auth",
   "description": "Official authentication provider for Adonis framework",
-  "version": "10.0.0",
+  "version": "10.1.0",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -51,50 +51,50 @@
     "quick:test": "cross-env NODE_DEBUG=\"adonisjs:auth:*\" node --enable-source-maps --import=@poppinss/ts-exec ./bin/test.js"
   },
   "devDependencies": {
-    "@adonisjs/assembler": "^8.0.0",
-    "@adonisjs/core": "^7.0.0",
+    "@adonisjs/assembler": "^8.4.0",
+    "@adonisjs/core": "^7.3.1",
     "@adonisjs/eslint-config": "^3.0.0",
     "@adonisjs/i18n": "^3.0.0",
-    "@adonisjs/lucid": "^22.0.0",
+    "@adonisjs/lucid": "^22.4.2",
     "@adonisjs/prettier-config": "^1.4.5",
-    "@adonisjs/session": "^8.0.0",
+    "@adonisjs/session": "^8.1.0",
     "@adonisjs/tsconfig": "^2.0.0",
     "@japa/api-client": "^3.2.1",
     "@japa/assert": "^4.2.0",
     "@japa/browser-client": "^2.3.0",
     "@japa/expect-type": "^2.0.4",
     "@japa/file-system": "^3.0.0",
-    "@japa/plugin-adonisjs": "^5.1.0",
+    "@japa/plugin-adonisjs": "^5.2.0",
     "@japa/runner": "^5.3.0",
     "@japa/snapshot": "^2.0.10",
     "@poppinss/ts-exec": "^1.4.4",
-    "@release-it/conventional-changelog": "^10.0.5",
+    "@release-it/conventional-changelog": "^10.0.6",
     "@types/basic-auth": "^1.1.8",
     "@types/luxon": "^3.7.1",
-    "@types/node": "^25.3.0",
+    "@types/node": "^25.5.2",
     "@types/set-cookie-parser": "^2.4.10",
-    "@types/sinon": "^21.0.0",
-    "better-sqlite3": "^12.6.2",
+    "@types/sinon": "^21.0.1",
+    "better-sqlite3": "^12.8.0",
     "c8": "^11.0.0",
     "convert-hrtime": "^5.0.0",
     "copyfiles": "^2.4.1",
     "cross-env": "^10.1.0",
     "del-cli": "^7.0.0",
-    "dotenv": "^17.3.1",
-    "eslint": "^10.0.2",
+    "dotenv": "^17.4.1",
+    "eslint": "^10.2.0",
     "luxon": "^3.7.2",
-    "mysql2": "^3.18.0",
-    "nock": "^14.0.11",
-    "pg": "^8.18.0",
-    "playwright": "^1.58.2",
+    "mysql2": "^3.21.0",
+    "nock": "^14.0.12",
+    "pg": "^8.20.0",
+    "playwright": "^1.59.1",
     "prettier": "^3.8.1",
     "release-it": "^19.2.4",
-    "set-cookie-parser": "^3.0.1",
-    "sinon": "^21.0.1",
+    "set-cookie-parser": "^3.1.0",
+    "sinon": "^21.0.3",
     "tedious": "^19.2.1",
     "timekeeper": "^2.3.1",
-    "tsdown": "^0.20.3",
-    "typescript": "^5.9.3"
+    "tsdown": "^0.21.7",
+    "typescript": "^6.0.2"
   },
   "dependencies": {
     "@adonisjs/presets": "^3.0.0",

package/build/auth_manager-hJTiBA2V.js

@@ -1,129 +0,0 @@
-import { n as E_UNAUTHORIZED_ACCESS } from "./errors-sGy-K8pd.js";
-import { t as debug_default } from "./debug-Ckko95-M.js";
-import { RuntimeException } from "@adonisjs/core/exceptions";
-import { HttpContextFactory } from "@adonisjs/core/factories/http";
-var Authenticator = class {
-	#config;
-	#guardsCache = {};
-	#authenticationAttemptedViaGuard;
-	#authenticatedViaGuard;
-	#ctx;
-	get defaultGuard() {
-		return this.#config.default;
-	}
-	get authenticatedViaGuard() {
-		return this.#authenticatedViaGuard;
-	}
-	get isAuthenticated() {
-		if (!this.#authenticationAttemptedViaGuard) return false;
-		return this.use(this.#authenticationAttemptedViaGuard).isAuthenticated;
-	}
-	get user() {
-		if (!this.#authenticationAttemptedViaGuard) return;
-		return this.use(this.#authenticationAttemptedViaGuard).user;
-	}
-	get authenticationAttempted() {
-		if (!this.#authenticationAttemptedViaGuard) return false;
-		return this.use(this.#authenticationAttemptedViaGuard).authenticationAttempted;
-	}
-	constructor(ctx, config) {
-		this.#ctx = ctx;
-		this.#config = config;
-		debug_default("creating authenticator. config %O", this.#config);
-	}
-	getUserOrFail() {
-		if (!this.#authenticationAttemptedViaGuard) throw new RuntimeException("Cannot access authenticated user. Please call \"auth.authenticate\" method first.");
-		return this.use(this.#authenticationAttemptedViaGuard).getUserOrFail();
-	}
-	use(guard) {
-		const guardToUse = guard || this.#config.default;
-		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];
-		debug_default("authenticator: creating guard. name: \"%s\"", guardToUse);
-		const guardInstance = guardFactory(this.#ctx);
-		this.#guardsCache[guardToUse] = guardInstance;
-		return guardInstance;
-	}
-	async authenticate() {
-		await this.authenticateUsing();
-		return this.getUserOrFail();
-	}
-	async check() {
-		this.#authenticationAttemptedViaGuard = this.defaultGuard;
-		const isAuthenticated = await this.use().check();
-		if (isAuthenticated) this.#authenticatedViaGuard = this.defaultGuard;
-		return isAuthenticated;
-	}
-	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
-		});
-	}
-	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;
-	}
-};
-var AuthenticatorClient = class {
-	#config;
-	#guardsCache = {};
-	get defaultGuard() {
-		return this.#config.default;
-	}
-	constructor(config) {
-		this.#config = config;
-		debug_default("creating authenticator client. config %O", this.#config);
-	}
-	use(guard) {
-		const guardToUse = guard || this.#config.default;
-		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];
-		debug_default("authenticator client: creating guard. name: \"%s\"", guardToUse);
-		const guardInstance = guardFactory(new HttpContextFactory().create());
-		this.#guardsCache[guardToUse] = guardInstance;
-		return guardInstance;
-	}
-};
-var AuthManager = class {
-	get defaultGuard() {
-		return this.config.default;
-	}
-	constructor(config) {
-		this.config = config;
-		this.config = config;
-	}
-	createAuthenticator(ctx) {
-		return new Authenticator(ctx, this.config);
-	}
-	createAuthenticatorClient() {
-		return new AuthenticatorClient(this.config);
-	}
-};
-export { AuthenticatorClient as n, Authenticator as r, AuthManager as t };

package/build/debug-Ckko95-M.js

@@ -1,3 +0,0 @@
-import { debuglog } from "node:util";
-var debug_default = debuglog("adonisjs:auth");
-export { debug_default as t };