@adonisjs/auth 9.5.1 → 10.0.0-next.1

package/build/{chunk-SAW2RPCA.js → chunk-MSPAYMZE.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-2VRS2VHB.js";
 import {
   E_UNAUTHORIZED_ACCESS
-} from "./chunk-MUPAP5IP.js";
+} from "./chunk-S5G5RTJX.js";
 
 // src/authenticator.ts
 import { RuntimeException } from "@adonisjs/core/exceptions";
@@ -85,14 +85,31 @@ var Authenticator = class {
     }
     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
+   * 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) {
@@ -105,6 +122,12 @@ var Authenticator = class {
   /**
    * 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;
@@ -123,6 +146,12 @@ var Authenticator = class {
    * 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();
@@ -132,6 +161,12 @@ var Authenticator = class {
    * 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;
@@ -149,6 +184,15 @@ var Authenticator = class {
    * 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];
@@ -172,6 +216,14 @@ var Authenticator = class {
    * 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) {
@@ -203,6 +255,17 @@ var AuthenticatorClient = class {
   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);
@@ -210,6 +273,12 @@ var AuthenticatorClient = class {
   /**
    * 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;
@@ -228,6 +297,17 @@ var AuthenticatorClient = class {
 
 // src/auth_manager.ts
 var AuthManager = class {
+  /**
+   * 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;
@@ -240,7 +320,13 @@ var AuthManager = class {
   }
   /**
    * Create an authenticator for a given HTTP request. The authenticator
-   * is used to authenticated in incoming HTTP request
+   * 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);
@@ -248,6 +334,10 @@ var AuthManager = class {
   /**
    * 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);

package/build/{chunk-MUPAP5IP.js → chunk-S5G5RTJX.js}

@@ -108,6 +108,13 @@ var 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) {
@@ -115,6 +122,18 @@ var E_UNAUTHORIZED_ACCESS = class extends Exception {
     }
     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;
@@ -122,6 +141,13 @@ var E_UNAUTHORIZED_ACCESS = class extends Exception {
   }
   /**
    * 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];
@@ -143,6 +169,13 @@ var E_INVALID_CREDENTIALS = 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) {
@@ -152,6 +185,13 @@ var E_INVALID_CREDENTIALS = class extends Exception {
   }
   /**
    * 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);

package/build/index.d.ts

@@ -1,11 +1,11 @@
-export * as errors from './src/errors.js';
-export { configure } from './configure.js';
-export * as symbols from './src/symbols.js';
-export { AuthManager } from './src/auth_manager.js';
-export { defineConfig } from './src/define_config.js';
-export { Authenticator } from './src/authenticator.js';
-export { AuthenticatorClient } from './src/authenticator_client.js';
-import type { withAuthFinder as withAuthFinderType } from './src/mixins/lucid.js';
+export * as errors from './src/errors.ts';
+export { configure } from './configure.ts';
+export * as symbols from './src/symbols.ts';
+export { AuthManager } from './src/auth_manager.ts';
+export { defineConfig } from './src/define_config.ts';
+export { Authenticator } from './src/authenticator.ts';
+export { AuthenticatorClient } from './src/authenticator_client.ts';
+import type { withAuthFinder as withAuthFinderType } from './src/mixins/lucid.ts';
 /**
  * @deprecated Import `withAuthFinder` from `@adonisjs/auth/mixins/lucid` instead
  */

package/build/index.js

@@ -2,11 +2,11 @@ import {
   AuthManager,
   Authenticator,
   AuthenticatorClient
-} from "./chunk-SAW2RPCA.js";
+} from "./chunk-MSPAYMZE.js";
 import "./chunk-2VRS2VHB.js";
 import {
   errors_exports
-} from "./chunk-MUPAP5IP.js";
+} from "./chunk-S5G5RTJX.js";
 import {
   __export
 } from "./chunk-UXA4FHST.js";

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

@@ -5,6 +5,20 @@ import { Secret } from '@adonisjs/core/helpers';
  *
  * It encapsulates the logic of creating an opaque token, generating
  * its hash and verifying its hash.
+ *
+ * @example
+ * const token = new AccessToken({
+ *   identifier: 1,
+ *   tokenableId: 123,
+ *   type: 'api',
+ *   hash: 'sha256hash',
+ *   createdAt: new Date(),
+ *   updatedAt: new Date(),
+ *   lastUsedAt: null,
+ *   expiresAt: null,
+ *   name: 'API Token',
+ *   abilities: ['read', 'write']
+ * })
  */
 export declare class AccessToken {
     /**
@@ -13,6 +27,16 @@ export declare class AccessToken {
      *
      * Returns null when unable to decode the token because of
      * invalid format or encoding.
+     *
+     * @param prefix - The token prefix to validate against
+     * @param value - The token value to decode
+     *
+     * @example
+     * const decoded = AccessToken.decode('oat_', 'oat_abc123.def456')
+     * if (decoded) {
+     *   console.log('Token ID:', decoded.identifier)
+     *   console.log('Secret:', decoded.secret.release())
+     * }
      */
     static decode(prefix: string, value: string): null | {
         identifier: string;
@@ -21,6 +45,14 @@ export declare class AccessToken {
     /**
      * Creates a transient token that can be shared with the persistence
      * layer.
+     *
+     * @param userId - The ID of the user for whom the token is created
+     * @param size - The size of the random secret to generate
+     * @param expiresIn - Optional expiration time (seconds or duration string)
+     *
+     * @example
+     * const transientToken = AccessToken.createTransientToken(123, 32, '7d')
+     * // Store transientToken in database
      */
     static createTransientToken(userId: string | number | BigInt, size: number, expiresIn?: string | number): {
         secret: Secret<string>;
@@ -32,6 +64,13 @@ export declare class AccessToken {
      * Creates a secret opaque token and its hash. The secret is
      * suffixed with a crc32 checksum for secret scanning tools
      * to easily identify the token.
+     *
+     * @param size - The size of the random string to generate
+     *
+     * @example
+     * const { secret, hash } = AccessToken.seed(32)
+     * console.log('Secret:', secret.release())
+     * console.log('Hash:', hash)
      */
     static seed(size: number): {
         secret: Secret<string>;
@@ -88,6 +127,25 @@ export declare class AccessToken {
      * is an array of abritary string values
      */
     abilities: string[];
+    /**
+     * Creates a new AccessToken instance
+     *
+     * @param attributes - Token attributes including identifier, user ID, type, hash, etc.
+     *
+     * @example
+     * const token = new AccessToken({
+     *   identifier: 1,
+     *   tokenableId: 123,
+     *   type: 'api',
+     *   hash: 'sha256hash',
+     *   createdAt: new Date(),
+     *   updatedAt: new Date(),
+     *   lastUsedAt: null,
+     *   expiresAt: new Date(Date.now() + 86400000),
+     *   name: 'Mobile App Token',
+     *   abilities: ['read:posts', 'write:posts']
+     * })
+     */
     constructor(attributes: {
         identifier: string | number | BigInt;
         tokenableId: string | number | BigInt;
@@ -104,14 +162,36 @@ export declare class AccessToken {
     });
     /**
      * Check if the token allows the given ability.
+     *
+     * @param ability - The ability to check
+     *
+     * @example
+     * if (token.allows('read:posts')) {
+     *   console.log('User can read posts')
+     * }
      */
     allows(ability: string): boolean;
     /**
      * Check if the token denies the ability.
+     *
+     * @param ability - The ability to check
+     *
+     * @example
+     * if (token.denies('delete:posts')) {
+     *   console.log('User cannot delete posts')
+     * }
      */
     denies(ability: string): boolean;
     /**
      * Authorize ability access using the current access token
+     *
+     * @param ability - The ability to authorize
+     *
+     * @throws {E_UNAUTHORIZED_ACCESS} When the token denies the ability
+     *
+     * @example
+     * token.authorize('write:posts') // Throws if not allowed
+     * console.log('Authorization successful')
      */
     authorize(ability: string): void;
     /**
@@ -120,12 +200,35 @@ export declare class AccessToken {
      * date.
      *
      * Tokens with no expiry never expire
+     *
+     * @example
+     * if (token.isExpired()) {
+     *   console.log('Token has expired')
+     * } else {
+     *   console.log('Token is still valid')
+     * }
      */
     isExpired(): boolean;
     /**
      * Verifies the value of a token against the pre-defined hash
+     *
+     * @param secret - The secret to verify against the stored hash
+     *
+     * @example
+     * const isValid = token.verify(new Secret('user-provided-secret'))
+     * if (isValid) {
+     *   console.log('Token is valid')
+     * }
      */
     verify(secret: Secret<string>): boolean;
+    /**
+     * Converts the token to a JSON representation suitable for API responses
+     *
+     * @example
+     * const tokenData = token.toJSON()
+     * console.log(tokenData.type) // 'bearer'
+     * console.log(tokenData.token) // 'oat_abc123.def456'
+     */
     toJSON(): {
         type: string;
         name: string | null;

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

@@ -8,9 +8,48 @@
  * Code taken from:
  * https://github.com/tsxper/crc32/blob/main/src/CRC32.ts
  */
+/**
+ * CRC32 implementation for adding recognizable checksums to tokens.
+ * This helps secret scanning tools easily detect tokens generated by AdonisJS.
+ *
+ * @example
+ * const crc = new CRC32()
+ * const checksum = crc.calculate('my-secret-token')
+ * console.log('Checksum:', checksum)
+ */
 export declare class CRC32 {
     #private;
+    /**
+     * Calculate CRC32 checksum for a string input
+     *
+     * @param input - The string to calculate checksum for
+     *
+     * @example
+     * const crc = new CRC32()
+     * const checksum = crc.calculate('hello-world')
+     * console.log('CRC32:', checksum)
+     */
     calculate(input: string): number;
+    /**
+     * Calculate CRC32 checksum for a string
+     *
+     * @param input - The string to process
+     *
+     * @example
+     * const crc = new CRC32()
+     * const result = crc.forString('test-string')
+     */
     forString(input: string): number;
+    /**
+     * Calculate CRC32 checksum for byte array
+     *
+     * @param bytes - The byte array to process
+     * @param accumulator - Optional accumulator for chained calculations
+     *
+     * @example
+     * const crc = new CRC32()
+     * const bytes = new TextEncoder().encode('hello')
+     * const result = crc.forBytes(bytes)
+     */
     forBytes(bytes: Uint8Array, accumulator?: number): number;
 }

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

@@ -1,9 +1,9 @@
 import type { HttpContext } from '@adonisjs/core/http';
 import type { ConfigProvider } from '@adonisjs/core/types';
-import { AccessTokensGuard } from './guard.js';
-import type { GuardConfigProvider } from '../../src/types.js';
-import { AccessTokensLucidUserProvider } from './user_providers/lucid.js';
-import type { LucidTokenable, AccessTokensUserProviderContract, AccessTokensLucidUserProviderOptions } from './types.js';
+import { AccessTokensGuard } from './guard.ts';
+import type { GuardConfigProvider } from '../../src/types.ts';
+import { AccessTokensLucidUserProvider } from './user_providers/lucid.ts';
+import type { LucidTokenable, AccessTokensUserProviderContract, AccessTokensLucidUserProviderOptions } from './types.ts';
 /**
  * Configures access tokens guard for authentication
  */

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

@@ -1,13 +1,26 @@
 import type { HttpContext } from '@adonisjs/core/http';
 import type { EmitterLike } from '@adonisjs/core/types/events';
-import type { AccessToken } from './access_token.js';
-import type { AuthClientResponse, GuardContract } from '../../src/types.js';
-import { GUARD_KNOWN_EVENTS, PROVIDER_REAL_USER } from '../../src/symbols.js';
-import type { AccessTokensGuardEvents, AccessTokensUserProviderContract } from './types.js';
+import type { AccessToken } from './access_token.ts';
+import type { AuthClientResponse, GuardContract } from '../../src/types.ts';
+import { GUARD_KNOWN_EVENTS, type PROVIDER_REAL_USER } from '../../src/symbols.ts';
+import type { AccessTokensGuardEvents, AccessTokensUserProviderContract } from './types.ts';
 /**
  * Implementation of access tokens guard for the Auth layer. The heavy lifting
  * of verifying tokens is done by the user provider. However, the guard is
  * used to seamlessly integrate with the auth layer of the package.
+ *
+ * @template UserProvider - The user provider contract
+ *
+ * @example
+ * const guard = new AccessTokensGuard(
+ *   'api',
+ *   ctx,
+ *   emitter,
+ *   userProvider
+ * )
+ *
+ * const user = await guard.authenticate()
+ * console.log('Authenticated user:', user.email)
  */
 export declare class AccessTokensGuard<UserProvider extends AccessTokensUserProviderContract<unknown>> implements GuardContract<UserProvider[typeof PROVIDER_REAL_USER] & {
     currentAccessToken: AccessToken;
@@ -47,12 +60,35 @@ export declare class AccessTokensGuard<UserProvider extends AccessTokensUserProv
     user?: UserProvider[typeof PROVIDER_REAL_USER] & {
         currentAccessToken: AccessToken;
     };
+    /**
+     * Creates a new AccessTokensGuard instance
+     *
+     * @param name - Unique name for the guard instance
+     * @param ctx - HTTP context for the current request
+     * @param emitter - Event emitter for guard events
+     * @param userProvider - User provider for token verification
+     *
+     * @example
+     * const guard = new AccessTokensGuard(
+     *   'api',
+     *   ctx,
+     *   emitter,
+     *   new TokenUserProvider()
+     * )
+     */
     constructor(name: string, ctx: HttpContext, emitter: EmitterLike<AccessTokensGuardEvents<UserProvider[typeof PROVIDER_REAL_USER] & {
         currentAccessToken: AccessToken;
     }>>, userProvider: UserProvider);
     /**
      * Returns an instance of the authenticated user. Or throws
      * an exception if the request is not authenticated.
+     *
+     * @throws {E_UNAUTHORIZED_ACCESS} When user is not authenticated
+     *
+     * @example
+     * const user = guard.getUserOrFail()
+     * console.log('User ID:', user.id)
+     * console.log('Current token:', user.currentAccessToken.name)
      */
     getUserOrFail(): UserProvider[typeof PROVIDER_REAL_USER] & {
         currentAccessToken: AccessToken;
@@ -60,12 +96,34 @@ export declare class AccessTokensGuard<UserProvider extends AccessTokensUserProv
     /**
      * Authenticate the current HTTP request by verifying the bearer
      * token or fails with an exception
+     *
+     * @throws {E_UNAUTHORIZED_ACCESS} When authentication fails
+     *
+     * @example
+     * try {
+     *   const user = await guard.authenticate()
+     *   console.log('Authenticated as:', user.email)
+     *   console.log('Token abilities:', user.currentAccessToken.abilities)
+     * } catch (error) {
+     *   console.log('Authentication failed')
+     * }
      */
     authenticate(): Promise<UserProvider[typeof PROVIDER_REAL_USER] & {
         currentAccessToken: AccessToken;
     }>;
     /**
      * Create a token for a user (sign in)
+     *
+     * @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 guard.createToken(user, ['read', 'write'], {
+     *   name: 'Mobile App',
+     *   expiresIn: '7d'
+     * })
+     * console.log('Token:', token.value.release())
      */
     createToken(user: UserProvider[typeof PROVIDER_REAL_USER], abilities?: string[], options?: {
         expiresIn?: string | number;
@@ -73,11 +131,23 @@ export declare class AccessTokensGuard<UserProvider extends AccessTokensUserProv
     }): Promise<AccessToken>;
     /**
      * Invalidates the currently authenticated token (sign out)
+     *
+     * @example
+     * await guard.invalidateToken()
+     * console.log('Token invalidated successfully')
      */
     invalidateToken(): Promise<boolean>;
     /**
      * Returns the Authorization header clients can use to authenticate
      * the request.
+     *
+     * @param user - The user to authenticate as
+     * @param abilities - Optional array of abilities
+     * @param options - Optional token configuration
+     *
+     * @example
+     * const clientAuth = await guard.authenticateAsClient(user, ['read'])
+     * // Use clientAuth.headers.authorization in API tests
      */
     authenticateAsClient(user: UserProvider[typeof PROVIDER_REAL_USER], abilities?: string[], options?: {
         expiresIn?: string | number;
@@ -85,8 +155,15 @@ export declare class AccessTokensGuard<UserProvider extends AccessTokensUserProv
     }): Promise<AuthClientResponse>;
     /**
      * Silently check if the user is authenticated or not. The
-     * method is same the "authenticate" method but does not
+     * method is same as the "authenticate" method but does not
      * throw any exceptions.
+     *
+     * @example
+     * const isAuthenticated = await guard.check()
+     * if (isAuthenticated) {
+     *   const user = guard.user
+     *   console.log('User is authenticated:', user.email)
+     * }
      */
     check(): Promise<boolean>;
 }

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

@@ -1,5 +1,5 @@
-export { AccessToken } from './access_token.js';
-export { AccessTokensGuard } from './guard.js';
-export { DbAccessTokensProvider } from './token_providers/db.js';
-export { tokensGuard, tokensUserProvider } from './define_config.js';
-export { AccessTokensLucidUserProvider } from './user_providers/lucid.js';
+export { AccessToken } from './access_token.ts';
+export { AccessTokensGuard } from './guard.ts';
+export { DbAccessTokensProvider } from './token_providers/db.ts';
+export { tokensGuard, tokensUserProvider } from './define_config.ts';
+export { AccessTokensLucidUserProvider } from './user_providers/lucid.ts';