@adonisjs/auth 9.5.0 → 10.0.0-next.0

package/build/src/define_config.d.ts

@@ -1,5 +1,5 @@
 import type { ConfigProvider } from '@adonisjs/core/types';
-import type { GuardConfigProvider, GuardFactory } from './types.js';
+import type { GuardConfigProvider, GuardFactory } from './types.ts';
 /**
  * Config resolved by the "defineConfig" method
  */
@@ -13,6 +13,24 @@ export type ResolvedAuthConfig<KnownGuards extends Record<string, GuardFactory |
  * 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')
+ *       })
+ *     })
+ *   }
+ * })
  */
 export declare function defineConfig<KnownGuards extends Record<string, GuardFactory | GuardConfigProvider<GuardFactory>>>(config: {
     default: keyof KnownGuards;

package/build/src/errors.d.ts

@@ -38,10 +38,24 @@ export declare const E_UNAUTHORIZED_ACCESS: {
          * 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: /*elided*/ any, ctx: HttpContext): string;
         /**
          * 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)
          */
         handle(error: /*elided*/ any, ctx: HttpContext): Promise<void>;
         name: string;
@@ -65,6 +79,9 @@ export declare const E_UNAUTHORIZED_ACCESS: {
 };
 /**
  * Exception is raised when user credentials are invalid
+ *
+ * @example
+ * throw new E_INVALID_CREDENTIALS('Invalid email or password')
  */
 export declare const E_INVALID_CREDENTIALS: {
     new (message?: string, options?: ErrorOptions & {
@@ -79,10 +96,24 @@ export declare const 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: /*elided*/ any, ctx: HttpContext): string;
         /**
          * 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)
          */
         handle(error: /*elided*/ any, ctx: HttpContext): Promise<void>;
         name: string;

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

@@ -1,15 +1,28 @@
 import type { HttpContext } from '@adonisjs/core/http';
 import type { NextFn } from '@adonisjs/core/types/http';
-import type { Authenticator } from '../authenticator.js';
-import type { Authenticators, GuardFactory } from '../types.js';
+import type { Authenticator } from '../authenticator.ts';
+import type { Authenticators, GuardFactory } from '../types.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')])
  */
 export default class InitializeAuthMiddleware {
+    /**
+     * 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
+     */
     handle(ctx: HttpContext, next: NextFn): Promise<any>;
 }
 declare module '@adonisjs/core/http' {

package/build/src/middleware/initialize_auth_middleware.js

@@ -2,6 +2,16 @@ import "../../chunk-UXA4FHST.js";
 
 // src/middleware/initialize_auth_middleware.ts
 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) {
     const auth = await ctx.containerResolver.make("auth.manager");
     ctx.auth = auth.createAuthenticator(ctx);

package/build/src/mixins/lucid.d.ts

@@ -20,6 +20,19 @@ type UserWithUserFinderClass<Model extends NormalizeConstructor<typeof BaseModel
  * - 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
+ * }
  */
 export declare function withAuthFinder(hash: () => Hash, options: {
     uids: string[];

package/build/src/mixins/lucid.js

@@ -1,6 +1,6 @@
 import {
   E_INVALID_CREDENTIALS
-} from "../../chunk-MUPAP5IP.js";
+} from "../../chunk-S5G5RTJX.js";
 import {
   __decorateClass
 } from "../../chunk-UXA4FHST.js";
@@ -21,8 +21,14 @@ function withAuthFinder(hash, options) {
       }
       /**
        * Finds the user for authentication via "verifyCredentials".
-       * Feel free to override this method customize the user
+       * 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();
@@ -32,6 +38,15 @@ function withAuthFinder(hash, options) {
       /**
        * 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) {
         if (!uid || !password) {
@@ -50,6 +65,16 @@ function withAuthFinder(hash, options) {
       /**
        * 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[options.passwordColumnName];

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

@@ -1,6 +1,6 @@
 import type { PluginFn } from '@japa/runner/types';
 import type { ApplicationService } from '@adonisjs/core/types';
-import type { Authenticators, GuardContract, GuardFactory } from '../../types.js';
+import type { Authenticators, GuardContract, GuardFactory } from '../../types.ts';
 declare module '@japa/api-client' {
     interface ApiRequest {
         authData: {
@@ -28,5 +28,14 @@ declare module '@japa/api-client' {
 /**
  * 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)
+ * ]
  */
 export declare const authApiClient: (app: ApplicationService) => PluginFn;

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

@@ -1,6 +1,6 @@
 import type { PluginFn } from '@japa/runner/types';
 import type { ApplicationService } from '@adonisjs/core/types';
-import type { Authenticators, GuardContract, GuardFactory } from '../../types.js';
+import type { Authenticators, GuardContract, GuardFactory } from '../../types.ts';
 declare module 'playwright' {
     interface BrowserContext {
         /**
@@ -24,5 +24,14 @@ declare module 'playwright' {
 /**
  * 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)
+ * ]
  */
 export declare const authBrowserClient: (app: ApplicationService) => PluginFn;

package/build/src/types.d.ts

@@ -1,108 +1,220 @@
 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';
+import type { AuthManager } from './auth_manager.ts';
+import type { GUARD_KNOWN_EVENTS } from './symbols.ts';
 /**
  * Authentication response to login a user as a client.
- * This response is used by Japa plugins
+ * This response is used by Japa plugins to set up authentication
+ * state during testing.
+ *
+ * @example
+ * const response: AuthClientResponse = {
+ *   cookies: { 'auth-token': 'abc123' },
+ *   session: { userId: 1 },
+ *   headers: { 'Authorization': 'Bearer token' }
+ * }
  */
 export interface AuthClientResponse {
+    /**
+     * HTTP headers to be set for authentication
+     */
     headers?: Record<string, any>;
+    /**
+     * Cookies to be set for authentication
+     */
     cookies?: Record<string, any>;
+    /**
+     * Session data to be set for authentication
+     */
     session?: Record<string, any>;
 }
 /**
  * A set of properties a guard must implement to authenticate
- * incoming HTTP requests
+ * incoming HTTP requests. This is the core contract that all
+ * authentication guards must follow.
+ *
+ * @template User - The type of the authenticated user
+ *
+ * @example
+ * class SessionGuard implements GuardContract<User> {
+ *   readonly driverName = 'session'
+ *   user?: User
+ *   isAuthenticated = false
+ *   authenticationAttempted = false
+ *
+ *   async authenticate(): Promise<User> {
+ *     // Implementation
+ *   }
+ * }
  */
 export interface GuardContract<User> {
     /**
-     * A unique name for the guard driver
+     * A unique name for the guard driver (e.g., 'session', 'api', 'basic')
      */
     readonly driverName: string;
     /**
-     * Reference to the currently authenticated user
+     * Reference to the currently authenticated user.
+     * Undefined when not authenticated.
      */
     user?: User;
     /**
-     * Returns logged-in user or throws an exception
+     * Returns logged-in user or throws an exception.
+     * Use this when you need to ensure the user is authenticated.
+     *
+     * @throws {RuntimeException} When user is not authenticated
      */
     getUserOrFail(): User;
     /**
-     * A boolean to know if the current request has
-     * been authenticated
+     * A boolean to know if the current request has been authenticated.
+     * Returns false if authentication was not attempted.
      */
     isAuthenticated: boolean;
     /**
      * Whether or not the authentication has been attempted
-     * during the current request
+     * during the current request. Used to differentiate between
+     * "not attempted" and "attempted but failed".
      */
     authenticationAttempted: boolean;
     /**
      * Authenticates the current request and throws an
      * exception if the request is not authenticated.
+     *
+     * @throws {E_UNAUTHORIZED_ACCESS} When authentication fails
      */
     authenticate(): Promise<User>;
     /**
      * Check if the current request has been authenticated
-     * without throwing an exception.
+     * without throwing an exception. Use this for optional
+     * authentication scenarios.
      */
     check(): Promise<boolean>;
     /**
-     * The method is used to authenticate the user as client.
-     * This method should return cookies, headers, or
-     * session state.
+     * The method is used to authenticate the user as client
+     * during testing. This method should return cookies, headers,
+     * or session state that can be used to simulate authentication.
      *
-     * The rest of the arguments can be anything the guard wants
-     * to accept
+     * @param user - The user to authenticate as
+     * @param args - Additional arguments specific to the guard
      */
     authenticateAsClient(user: User, ...args: any[]): Promise<AuthClientResponse>;
     /**
-     * Aymbol for infer the events emitted by a specific
-     * guard
+     * Symbol for inferring the events emitted by a specific guard.
+     * Used internally for type inference of guard events.
      */
     [GUARD_KNOWN_EVENTS]: unknown;
 }
 /**
- * The guard factory method is called by the create an instance
- * of a guard during an HTTP request
+ * The guard factory method is called to create an instance
+ * of a guard during an HTTP request. Each guard factory receives
+ * the HTTP context and returns a configured guard instance.
+ *
+ * @param ctx - The HTTP context for the current request
+ *
+ * @example
+ * const sessionGuardFactory: GuardFactory = (ctx) => {
+ *   return new SessionGuard(ctx)
+ * }
  */
 export type GuardFactory = (ctx: HttpContext) => GuardContract<unknown>;
 /**
- * Config provider for registering guards. The "name" property
- * is reference to the object key to which the guard is
- * assigned.
+ * Config provider for registering guards. Used for lazy loading
+ * of guard factories. The resolver function is called with the
+ * guard name and application instance to create the factory.
+ *
+ * @template Factory - The guard factory type
+ *
+ * @example
+ * const guardProvider: GuardConfigProvider<SessionGuardFactory> = {
+ *   resolver: async (name, app) => {
+ *     const sessionConfig = await app.container.make('session.config')
+ *     return (ctx) => new SessionGuard(ctx, sessionConfig)
+ *   }
+ * }
  */
 export type GuardConfigProvider<Factory extends GuardFactory> = {
+    /**
+     * Resolver function that creates the guard factory
+     *
+     * @param name - The name of the guard being resolved
+     * @param app - The application service instance
+     */
     resolver: (name: string, app: ApplicationService) => Promise<Factory>;
 };
 /**
  * Authenticators are inferred inside the user application
- * from the config file
+ * from the config file. This interface is augmented automatically
+ * when you define your auth configuration.
+ *
+ * @example
+ * // After defining your auth config, this interface will be augmented:
+ * declare module '@adonisjs/auth/types' {
+ *   interface Authenticators {
+ *     web: SessionGuardFactory
+ *     api: TokenGuardFactory
+ *   }
+ * }
  */
 export interface Authenticators {
 }
 /**
- * Infer authenticators from the auth config
+ * Infer authenticators from the auth config. This utility type
+ * extracts the guards configuration from a config provider.
+ *
+ * @template Config - The auth config provider type
+ *
+ * @example
+ * type MyAuthenticators = InferAuthenticators<typeof authConfig>
+ * // Results in: { web: SessionGuardFactory, api: TokenGuardFactory }
  */
 export type InferAuthenticators<Config extends ConfigProvider<{
     default: unknown;
     guards: unknown;
 }>> = Awaited<ReturnType<Config['resolver']>>['guards'];
 /**
- * Helper to convert union to intersection
+ * Helper to convert union to intersection. This utility type
+ * transforms a union of types into an intersection of types.
+ * Used internally for merging guard events.
+ *
+ * @template U - The union type to convert
+ *
+ * @example
+ * type Union = { a: string } | { b: number }
+ * type Intersection = UnionToIntersection<Union>
+ * // Results in: { a: string } & { b: number }
  */
 type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
 /**
- * Infer events based upon the configure authenticators
+ * Infer events based upon the configured authenticators.
+ * This type extracts and merges all events from all configured
+ * guards into a single intersection type.
+ *
+ * @template KnownAuthenticators - Record of guard names to guard factories
+ *
+ * @example
+ * type AuthEvents = InferAuthEvents<{
+ *   web: SessionGuardFactory
+ *   api: TokenGuardFactory
+ * }>
+ * // Results in intersection of all guard events
  */
 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.
+ * configured using the config stored within the user app.
+ * This interface is used for dependency injection and provides
+ * type-safe access to the auth manager.
+ *
+ * @example
+ * // In a service or controller:
+ * class UserController {
+ *   constructor(private auth: AuthService) {}
+ *
+ *   async login() {
+ *     const user = await this.auth.createAuthenticator(ctx).authenticate()
+ *   }
+ * }
  */
 export interface AuthService extends AuthManager<Authenticators extends Record<string, GuardFactory> ? Authenticators : never> {
 }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@adonisjs/auth",
   "description": "Official authentication provider for Adonis framework",
-  "version": "9.5.0",
+  "version": "10.0.0-next.0",
   "engines": {
-    "node": ">=18.16.0"
+    "node": ">=24.0.0"
   },
   "main": "build/index.js",
   "type": "module",
@@ -48,28 +48,27 @@
     "prepublishOnly": "npm run build",
     "release": "release-it",
     "version": "npm run build",
-    "quick:test": "cross-env NODE_DEBUG=\"adonisjs:auth:*\" node --enable-source-maps --import=ts-node-maintained/register/esm ./bin/test.js"
+    "quick:test": "cross-env NODE_DEBUG=\"adonisjs:auth:*\" node --enable-source-maps --import=@poppinss/ts-exec ./bin/test.js"
   },
   "devDependencies": {
-    "@adonisjs/assembler": "^7.8.2",
-    "@adonisjs/core": "^6.19.0",
-    "@adonisjs/eslint-config": "^2.1.2",
-    "@adonisjs/hash": "^9.1.1",
-    "@adonisjs/i18n": "^2.2.2",
-    "@adonisjs/lucid": "^21.8.0",
+    "@adonisjs/assembler": "^8.0.0-next.9",
+    "@adonisjs/core": "^7.0.0-next.1",
+    "@adonisjs/eslint-config": "^3.0.0-next.1",
+    "@adonisjs/i18n": "^3.0.0-next.0",
+    "@adonisjs/lucid": "^22.0.0-next.0",
     "@adonisjs/prettier-config": "^1.4.5",
-    "@adonisjs/session": "^7.5.1",
-    "@adonisjs/tsconfig": "^1.4.1",
+    "@adonisjs/session": "^8.0.0-next.0",
+    "@adonisjs/tsconfig": "^2.0.0-next.0",
     "@japa/api-client": "^3.1.0",
     "@japa/assert": "^4.1.1",
     "@japa/browser-client": "^2.1.1",
     "@japa/expect-type": "^2.0.3",
     "@japa/file-system": "^2.3.2",
-    "@japa/plugin-adonisjs": "^4.0.0",
+    "@japa/plugin-adonisjs": "^5.0.0-next.0",
     "@japa/runner": "^4.4.0",
     "@japa/snapshot": "^2.0.9",
+    "@poppinss/ts-exec": "^1.4.1",
     "@release-it/conventional-changelog": "^10.0.1",
-    "@swc/core": "1.13.5",
     "@types/basic-auth": "^1.1.8",
     "@types/luxon": "^3.7.1",
     "@types/node": "^24.5.2",
@@ -94,24 +93,26 @@
     "sqlite3": "^5.1.7",
     "tedious": "^18.6.1",
     "timekeeper": "^2.3.1",
-    "ts-node-maintained": "^10.9.6",
     "tsup": "^8.5.0",
     "typescript": "^5.9.2"
   },
   "dependencies": {
-    "@adonisjs/presets": "^2.6.4",
-    "@poppinss/utils": "^6.10.1",
+    "@adonisjs/presets": "^3.0.0-next.0",
     "basic-auth": "^2.0.1"
   },
   "peerDependencies": {
-    "@adonisjs/core": "^6.11.0",
-    "@adonisjs/lucid": "^20.0.0 || ^21.0.1",
-    "@adonisjs/session": "^7.4.1",
-    "@japa/api-client": "^2.0.3 || ^3.0.0",
-    "@japa/browser-client": "^2.0.3",
-    "@japa/plugin-adonisjs": "^3.0.1 || ^4.0.0"
+    "@adonisjs/assembler": "^8.0.0-next.9",
+    "@adonisjs/core": "^7.0.0-next.1",
+    "@adonisjs/lucid": "^22.0.0-next.0",
+    "@adonisjs/session": "^8.0.0-next.0",
+    "@japa/api-client": "^3.1.0",
+    "@japa/browser-client": "^2.1.1",
+    "@japa/plugin-adonisjs": "^5.0.0-next.0"
   },
   "peerDependenciesMeta": {
+    "@adonisjs/assembler": {
+      "optional": true
+    },
     "@adonisjs/lucid": {
       "optional": true
     },