@adonisjs/auth 9.5.0 → 10.0.0-next.0

package/build/modules/access_tokens_guard/token_providers/db.d.ts

@@ -1,18 +1,37 @@
 import type { Secret } from '@adonisjs/core/helpers';
 import type { LucidModel } from '@adonisjs/lucid/types/model';
-import { AccessToken } from '../access_token.js';
-import type { AccessTokenDbColumns, AccessTokensProviderContract, DbAccessTokensProviderOptions } from '../types.js';
+import { AccessToken } from '../access_token.ts';
+import type { AccessTokenDbColumns, AccessTokensProviderContract, DbAccessTokensProviderOptions } from '../types.ts';
 /**
  * DbAccessTokensProvider uses lucid database service to fetch and
  * persist tokens for a given user.
  *
  * The user must be an instance of the associated user model.
+ *
+ * @template TokenableModel - The Lucid model that can have tokens
+ *
+ * @example
+ * const provider = new DbAccessTokensProvider({
+ *   tokenableModel: () => import('#models/user'),
+ *   table: 'api_tokens',
+ *   type: 'api_token',
+ *   prefix: 'api_'
+ * })
  */
 export declare class DbAccessTokensProvider<TokenableModel extends LucidModel> implements AccessTokensProviderContract<TokenableModel> {
     #private;
     protected options: DbAccessTokensProviderOptions<TokenableModel>;
     /**
      * Create tokens provider instance for a given Lucid model
+     *
+     * @param model - The tokenable model factory function
+     * @param options - Optional configuration options
+     *
+     * @example
+     * const provider = DbAccessTokensProvider.forModel(
+     *   () => import('#models/user'),
+     *   { prefix: 'api_', type: 'api_token' }
+     * )
      */
     static forModel<TokenableModel extends LucidModel>(model: DbAccessTokensProviderOptions<TokenableModel>['tokenableModel'], options?: Omit<DbAccessTokensProviderOptions<TokenableModel>, 'tokenableModel'>): DbAccessTokensProvider<TokenableModel>;
     /**
@@ -37,17 +56,57 @@ export declare class DbAccessTokensProvider<TokenableModel extends LucidModel> i
      * secure random string.
      */
     protected tokenSecretLength: number;
+    /**
+     * Creates a new DbAccessTokensProvider instance
+     *
+     * @param options - Configuration options for the provider
+     *
+     * @example
+     * const provider = new DbAccessTokensProvider({
+     *   tokenableModel: () => import('#models/user'),
+     *   table: 'auth_access_tokens',
+     *   tokenSecretLength: 40,
+     *   type: 'auth_token',
+     *   prefix: 'oat_'
+     * })
+     */
     constructor(options: DbAccessTokensProviderOptions<TokenableModel>);
     /**
-     * Maps a database row to an instance token instance
+     * Maps a database row to an AccessToken instance
+     *
+     * @param dbRow - The database row containing token data
+     *
+     * @example
+     * const token = provider.dbRowToAccessToken({
+     *   id: 1,
+     *   tokenable_id: 123,
+     *   type: 'auth_token',
+     *   hash: 'sha256hash',
+     *   // ... other columns
+     * })
      */
     protected dbRowToAccessToken(dbRow: AccessTokenDbColumns): AccessToken;
     /**
      * Returns a query client instance from the parent model
+     *
+     * @example
+     * const db = await provider.getDb()
+     * const tokens = await db.from('auth_access_tokens').select('*')
      */
     protected getDb(): Promise<import("@adonisjs/lucid/types/database").QueryClientContract>;
     /**
      * Create a token for a user
+     *
+     * @param user - The user instance to create a token for
+     * @param abilities - Array of abilities the token should have
+     * @param options - Optional token configuration
+     *
+     * @example
+     * const token = await provider.create(user, ['read', 'write'], {
+     *   name: 'Mobile App Token',
+     *   expiresIn: '7d'
+     * })
+     * console.log('Token:', token.value.release())
      */
     create(user: InstanceType<TokenableModel>, abilities?: string[], options?: {
         name?: string;
@@ -55,14 +114,37 @@ export declare class DbAccessTokensProvider<TokenableModel extends LucidModel> i
     }): Promise<AccessToken>;
     /**
      * Find a token for a user by the token id
+     *
+     * @param user - The user instance that owns the token
+     * @param identifier - The token identifier to search for
+     *
+     * @example
+     * const token = await provider.find(user, 123)
+     * if (token) {
+     *   console.log('Found token:', token.name)
+     * }
      */
     find(user: InstanceType<TokenableModel>, identifier: string | number | BigInt): Promise<AccessToken | null>;
     /**
      * Delete a token by its id
+     *
+     * @param user - The user instance that owns the token
+     * @param identifier - The token identifier to delete
+     *
+     * @example
+     * const deletedCount = await provider.delete(user, 123)
+     * console.log('Deleted tokens:', deletedCount)
      */
     delete(user: InstanceType<TokenableModel>, identifier: string | number | BigInt): Promise<number>;
     /**
-     * Returns all the tokens a given user
+     * Returns all the tokens for a given user
+     *
+     * @param user - The user instance to get tokens for
+     *
+     * @example
+     * const tokens = await provider.all(user)
+     * console.log('User has', tokens.length, 'tokens')
+     * tokens.forEach(token => console.log(token.name))
      */
     all(user: InstanceType<TokenableModel>): Promise<AccessToken[]>;
     /**
@@ -71,10 +153,26 @@ export declare class DbAccessTokensProvider<TokenableModel extends LucidModel> i
      *
      * Returns null when unable to verify the token or find it
      * inside the storage
+     *
+     * @param tokenValue - The token value to verify
+     *
+     * @example
+     * const token = await provider.verify(new Secret('oat_abc123.def456'))
+     * if (token && !token.isExpired()) {
+     *   console.log('Valid token for user:', token.tokenableId)
+     * }
      */
     verify(tokenValue: Secret<string>): Promise<AccessToken | null>;
     /**
      * Invalidates a token identified by its publicly shared token
+     *
+     * @param tokenValue - The token value to invalidate
+     *
+     * @example
+     * const wasInvalidated = await provider.invalidate(new Secret('oat_abc123.def456'))
+     * if (wasInvalidated) {
+     *   console.log('Token successfully invalidated')
+     * }
      */
     invalidate(tokenValue: Secret<string>): Promise<boolean>;
 }

package/build/modules/access_tokens_guard/types.d.ts

@@ -2,8 +2,8 @@ import type { Secret } from '@adonisjs/core/helpers';
 import type { HttpContext } from '@adonisjs/core/http';
 import type { Exception } from '@adonisjs/core/exceptions';
 import type { LucidModel } from '@adonisjs/lucid/types/model';
-import type { AccessToken } from './access_token.js';
-import type { PROVIDER_REAL_USER } from '../../src/symbols.js';
+import type { AccessToken } from './access_token.ts';
+import type { PROVIDER_REAL_USER } from '../../src/symbols.ts';
 /**
  * Options accepted by the tokens provider that uses lucid
  * database service to fetch and persist tokens.

package/build/modules/access_tokens_guard/user_providers/lucid.d.ts

@@ -1,10 +1,19 @@
-import { Secret } from '@adonisjs/core/helpers';
-import { AccessToken } from '../access_token.js';
-import { PROVIDER_REAL_USER } from '../../../src/symbols.js';
-import type { LucidTokenable, AccessTokensGuardUser, AccessTokensUserProviderContract, AccessTokensLucidUserProviderOptions } from '../types.js';
+import { type Secret } from '@adonisjs/core/helpers';
+import { type AccessToken } from '../access_token.ts';
+import { PROVIDER_REAL_USER } from '../../../src/symbols.ts';
+import type { LucidTokenable, AccessTokensGuardUser, AccessTokensUserProviderContract, AccessTokensLucidUserProviderOptions } from '../types.ts';
 /**
  * Uses a lucid model to verify access tokens and find a user during
  * authentication
+ *
+ * @template TokenableProperty - The property name that holds the tokens provider
+ * @template UserModel - The Lucid model representing the user
+ *
+ * @example
+ * const userProvider = new AccessTokensLucidUserProvider({
+ *   model: () => import('#models/user'),
+ *   tokens: 'accessTokens'
+ * })
  */
 export declare class AccessTokensLucidUserProvider<TokenableProperty extends string, UserModel extends LucidTokenable<TokenableProperty>> implements AccessTokensUserProviderContract<InstanceType<UserModel>> {
     /**
@@ -16,6 +25,17 @@ export declare class AccessTokensLucidUserProvider<TokenableProperty extends str
      * Reference to the lazily imported model
      */
     protected model?: UserModel;
+    /**
+     * Creates a new AccessTokensLucidUserProvider instance
+     *
+     * @param options - Configuration options for the user provider
+     *
+     * @example
+     * const provider = new AccessTokensLucidUserProvider({
+     *   model: () => import('#models/user'),
+     *   tokens: 'accessTokens'
+     * })
+     */
     constructor(
     /**
      * Lucid provider options
@@ -24,18 +44,44 @@ export declare class AccessTokensLucidUserProvider<TokenableProperty extends str
     /**
      * Imports the model from the provider, returns and caches it
      * for further operations.
+     *
+     * @example
+     * const UserModel = await provider.getModel()
+     * const user = await UserModel.find(1)
      */
     protected getModel(): Promise<UserModel>;
     /**
      * Returns the tokens provider associated with the user model
+     *
+     * @example
+     * const tokensProvider = await provider.getTokensProvider()
+     * const token = await tokensProvider.create(user, ['read'])
      */
     protected getTokensProvider(): Promise<UserModel[TokenableProperty]>;
     /**
      * Creates an adapter user for the guard
+     *
+     * @param user - The user model instance
+     *
+     * @example
+     * const guardUser = await provider.createUserForGuard(user)
+     * console.log('User ID:', guardUser.getId())
+     * console.log('Original user:', guardUser.getOriginal())
      */
     createUserForGuard(user: InstanceType<UserModel>): Promise<AccessTokensGuardUser<InstanceType<UserModel>>>;
     /**
      * Create a token for a given user
+     *
+     * @param user - The user to create a token for
+     * @param abilities - Optional array of abilities the token should have
+     * @param options - Optional token configuration
+     *
+     * @example
+     * const token = await provider.createToken(user, ['read', 'write'], {
+     *   name: 'API Token',
+     *   expiresIn: '30d'
+     * })
+     * console.log('Created token:', token.value.release())
      */
     createToken(user: InstanceType<UserModel>, abilities?: string[] | undefined, options?: {
         name?: string;
@@ -43,15 +89,42 @@ export declare class AccessTokensLucidUserProvider<TokenableProperty extends str
     }): Promise<AccessToken>;
     /**
      * Invalidates a token identified by its publicly shared token
+     *
+     * @param tokenValue - The token value to invalidate
+     *
+     * @example
+     * const wasInvalidated = await provider.invalidateToken(
+     *   new Secret('oat_abc123.def456')
+     * )
+     * console.log('Token invalidated:', wasInvalidated)
      */
     invalidateToken(tokenValue: Secret<string>): Promise<boolean>;
     /**
      * Finds a user by the user id
+     *
+     * @param identifier - The user identifier to search for
+     *
+     * @example
+     * const guardUser = await provider.findById(123)
+     * if (guardUser) {
+     *   const originalUser = guardUser.getOriginal()
+     *   console.log('Found user:', originalUser.email)
+     * }
      */
     findById(identifier: string | number | BigInt): Promise<AccessTokensGuardUser<InstanceType<UserModel>> | null>;
     /**
      * Verifies a publicly shared access token and returns an
      * access token for it.
+     *
+     * @param tokenValue - The token value to verify
+     *
+     * @example
+     * const token = await provider.verifyToken(
+     *   new Secret('oat_abc123.def456')
+     * )
+     * if (token && !token.isExpired()) {
+     *   console.log('Valid token with abilities:', token.abilities)
+     * }
      */
     verifyToken(tokenValue: Secret<string>): Promise<AccessToken | null>;
 }

package/build/modules/basic_auth_guard/define_config.d.ts

@@ -1,9 +1,9 @@
 import type { HttpContext } from '@adonisjs/core/http';
 import type { ConfigProvider } from '@adonisjs/core/types';
-import { BasicAuthGuard } from './guard.js';
-import type { GuardConfigProvider } from '../../src/types.js';
-import { BasicAuthLucidUserProvider } from './user_providers/lucid.js';
-import type { LucidAuthenticatable, BasicAuthUserProviderContract, BasicAuthLucidUserProviderOptions } from './types.js';
+import { BasicAuthGuard } from './guard.ts';
+import type { GuardConfigProvider } from '../../src/types.ts';
+import { BasicAuthLucidUserProvider } from './user_providers/lucid.ts';
+import type { LucidAuthenticatable, BasicAuthUserProviderContract, BasicAuthLucidUserProviderOptions } from './types.ts';
 /**
  * Configures basic auth guard for authentication
  */

package/build/modules/basic_auth_guard/guard.d.ts

@@ -1,10 +1,23 @@
 import type { HttpContext } from '@adonisjs/core/http';
 import type { EmitterLike } from '@adonisjs/core/types/events';
-import type { AuthClientResponse, GuardContract } from '../../src/types.js';
-import { GUARD_KNOWN_EVENTS, PROVIDER_REAL_USER } from '../../src/symbols.js';
-import type { BasicAuthGuardEvents, BasicAuthUserProviderContract } from './types.js';
+import type { AuthClientResponse, GuardContract } from '../../src/types.ts';
+import { GUARD_KNOWN_EVENTS, type PROVIDER_REAL_USER } from '../../src/symbols.ts';
+import type { BasicAuthGuardEvents, BasicAuthUserProviderContract } from './types.ts';
 /**
  * BasicAuth guard implements the HTTP Authentication protocol
+ *
+ * @template UserProvider - The user provider contract
+ *
+ * @example
+ * const guard = new BasicAuthGuard(
+ *   'basic',
+ *   ctx,
+ *   emitter,
+ *   userProvider
+ * )
+ *
+ * const user = await guard.authenticate()
+ * console.log('Authenticated user:', user.email)
  */
 export declare class BasicAuthGuard<UserProvider extends BasicAuthUserProviderContract<unknown>> implements GuardContract<UserProvider[typeof PROVIDER_REAL_USER]> {
     #private;

package/build/modules/basic_auth_guard/main.d.ts

@@ -1,3 +1,3 @@
-export { BasicAuthGuard } from './guard.js';
-export { basicAuthGuard, basicAuthUserProvider } from './define_config.js';
-export { BasicAuthLucidUserProvider } from './user_providers/lucid.js';
+export { BasicAuthGuard } from './guard.ts';
+export { BasicAuthLucidUserProvider } from './user_providers/lucid.ts';
+export { basicAuthGuard, basicAuthUserProvider } from './define_config.ts';

package/build/modules/basic_auth_guard/main.js

@@ -1,6 +1,6 @@
 import {
   E_UNAUTHORIZED_ACCESS
-} from "../../chunk-MUPAP5IP.js";
+} from "../../chunk-S5G5RTJX.js";
 import "../../chunk-UXA4FHST.js";
 
 // modules/basic_auth_guard/guard.ts
@@ -157,6 +157,16 @@ var BasicAuthGuard = class {
 // modules/basic_auth_guard/user_providers/lucid.ts
 import { RuntimeException } from "@adonisjs/core/exceptions";
 var BasicAuthLucidUserProvider = class {
+  /**
+   * Creates a new BasicAuthLucidUserProvider instance
+   *
+   * @param options - Configuration options for the user provider
+   *
+   * @example
+   * const provider = new BasicAuthLucidUserProvider({
+   *   model: () => import('#models/user')
+   * })
+   */
   constructor(options) {
     this.options = options;
   }

package/build/modules/basic_auth_guard/types.d.ts

@@ -1,7 +1,7 @@
 import type { HttpContext } from '@adonisjs/core/http';
 import type { Exception } from '@adonisjs/core/exceptions';
 import type { LucidModel } from '@adonisjs/lucid/types/model';
-import type { PROVIDER_REAL_USER } from '../../src/symbols.js';
+import type { PROVIDER_REAL_USER } from '../../src/symbols.ts';
 /**
  * A lucid model with verify credentials method to verify user
  * credentials during authentication.

package/build/modules/basic_auth_guard/user_providers/lucid.d.ts

@@ -1,8 +1,15 @@
-import { PROVIDER_REAL_USER } from '../../../src/symbols.js';
-import type { BasicAuthGuardUser, LucidAuthenticatable, BasicAuthUserProviderContract, BasicAuthLucidUserProviderOptions } from '../types.js';
+import { PROVIDER_REAL_USER } from '../../../src/symbols.ts';
+import type { BasicAuthGuardUser, LucidAuthenticatable, BasicAuthUserProviderContract, BasicAuthLucidUserProviderOptions } from '../types.ts';
 /**
  * Uses a Lucid model to verify access tokens and find a user during
  * authentication
+ *
+ * @template UserModel - The Lucid model representing the user
+ *
+ * @example
+ * const userProvider = new BasicAuthLucidUserProvider({
+ *   model: () => import('#models/user')
+ * })
  */
 export declare class BasicAuthLucidUserProvider<UserModel extends LucidAuthenticatable> implements BasicAuthUserProviderContract<InstanceType<UserModel>> {
     /**
@@ -14,6 +21,16 @@ export declare class BasicAuthLucidUserProvider<UserModel extends LucidAuthentic
      * Reference to the lazily imported model
      */
     protected model?: UserModel;
+    /**
+     * Creates a new BasicAuthLucidUserProvider instance
+     *
+     * @param options - Configuration options for the user provider
+     *
+     * @example
+     * const provider = new BasicAuthLucidUserProvider({
+     *   model: () => import('#models/user')
+     * })
+     */
     constructor(
     /**
      * Lucid provider options

package/build/modules/session_guard/define_config.d.ts

@@ -1,9 +1,9 @@
 import type { HttpContext } from '@adonisjs/core/http';
 import type { ConfigProvider } from '@adonisjs/core/types';
-import { SessionGuard } from './guard.js';
-import type { GuardConfigProvider } from '../../src/types.js';
-import { SessionLucidUserProvider } from './user_providers/lucid.js';
-import type { SessionGuardOptions, LucidAuthenticatable, SessionUserProviderContract, SessionLucidUserProviderOptions, SessionWithTokensUserProviderContract } from './types.js';
+import { SessionGuard } from './guard.ts';
+import type { GuardConfigProvider } from '../../src/types.ts';
+import { SessionLucidUserProvider } from './user_providers/lucid.ts';
+import type { SessionGuardOptions, LucidAuthenticatable, SessionUserProviderContract, SessionLucidUserProviderOptions, SessionWithTokensUserProviderContract } from './types.ts';
 /**
  * Configures session tokens guard for authentication
  */

package/build/modules/session_guard/guard.d.ts

@@ -1,11 +1,26 @@
 import type { HttpContext } from '@adonisjs/core/http';
 import type { EmitterLike } from '@adonisjs/core/types/events';
-import type { AuthClientResponse, GuardContract } from '../../src/types.js';
-import { GUARD_KNOWN_EVENTS, PROVIDER_REAL_USER } from '../../src/symbols.js';
-import type { SessionGuardEvents, SessionGuardOptions, SessionUserProviderContract, SessionWithTokensUserProviderContract } from './types.js';
+import type { AuthClientResponse, GuardContract } from '../../src/types.ts';
+import { GUARD_KNOWN_EVENTS, type PROVIDER_REAL_USER } from '../../src/symbols.ts';
+import type { SessionGuardEvents, SessionGuardOptions, SessionUserProviderContract, SessionWithTokensUserProviderContract } from './types.ts';
 /**
  * Session guard uses AdonisJS session store to track logged-in
  * user information.
+ *
+ * @template UseRememberTokens - Whether the guard supports remember me tokens
+ * @template UserProvider - The user provider contract
+ *
+ * @example
+ * const guard = new SessionGuard(
+ *   'web',
+ *   ctx,
+ *   { useRememberMeTokens: true },
+ *   emitter,
+ *   userProvider
+ * )
+ *
+ * const user = await guard.authenticate()
+ * console.log('Authenticated user:', user.email)
  */
 export declare class SessionGuard<UseRememberTokens extends boolean, UserProvider extends UseRememberTokens extends true ? SessionWithTokensUserProviderContract<unknown> : SessionUserProviderContract<unknown>> implements GuardContract<UserProvider[typeof PROVIDER_REAL_USER]> {
     #private;
@@ -57,12 +72,36 @@ export declare class SessionGuard<UseRememberTokens extends boolean, UserProvide
     /**
      * The key used to store the logged-in user id inside
      * session
+     *
+     * @example
+     * console.log('Session key:', guard.sessionKeyName) // 'auth_web'
      */
     get sessionKeyName(): string;
     /**
      * The key used to store the remember me token cookie
+     *
+     * @example
+     * console.log('Remember me key:', guard.rememberMeKeyName) // 'remember_web'
      */
     get rememberMeKeyName(): string;
+    /**
+     * Creates a new SessionGuard instance
+     *
+     * @param name - Unique name for the guard instance
+     * @param ctx - HTTP context for the current request
+     * @param options - Configuration options for the session guard
+     * @param emitter - Event emitter for guard events
+     * @param userProvider - User provider for authentication
+     *
+     * @example
+     * const guard = new SessionGuard(
+     *   'web',
+     *   ctx,
+     *   { useRememberMeTokens: true, rememberMeTokensAge: '30d' },
+     *   emitter,
+     *   userProvider
+     * )
+     */
     constructor(name: string, ctx: HttpContext, options: SessionGuardOptions<UseRememberTokens>, emitter: EmitterLike<SessionGuardEvents<UserProvider[typeof PROVIDER_REAL_USER]>>, userProvider: UserProvider);
     /**
      * Returns an instance of the authenticated user. Or throws

package/build/modules/session_guard/main.d.ts

@@ -1,5 +1,5 @@
-export { RememberMeToken } from './remember_me_token.js';
-export { SessionGuard } from './guard.js';
-export { DbRememberMeTokensProvider } from './token_providers/db.js';
-export { sessionGuard, sessionUserProvider } from './define_config.js';
-export { SessionLucidUserProvider } from './user_providers/lucid.js';
+export { SessionGuard } from './guard.ts';
+export { RememberMeToken } from './remember_me_token.ts';
+export { DbRememberMeTokensProvider } from './token_providers/db.ts';
+export { SessionLucidUserProvider } from './user_providers/lucid.ts';
+export { sessionGuard, sessionUserProvider } from './define_config.ts';