@adonisjs/auth 9.4.2 → 10.0.0-next.0

package/build/modules/access_tokens_guard/main.js

@@ -1,6 +1,6 @@
 import {
   E_UNAUTHORIZED_ACCESS
-} from "../../chunk-MUPAP5IP.js";
+} from "../../chunk-S5G5RTJX.js";
 import "../../chunk-UXA4FHST.js";
 
 // modules/access_tokens_guard/access_token.ts
@@ -295,13 +295,43 @@ var CRC32 = class {
     }
     return 4294967295 - num * -1 + 1;
   }
+  /**
+   * 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) {
     return this.forString(input);
   }
+  /**
+   * 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) {
     const bytes = this.#strToBytes(input);
     return this.forBytes(bytes);
   }
+  /**
+   * 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, accumulator) {
     const crc = this.#calculateBytes(bytes, accumulator);
     return this.#crcToUint(crc);
@@ -316,6 +346,16 @@ var AccessToken = class {
    *
    * 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, value) {
     if (typeof value !== "string" || !value.startsWith(`${prefix}`)) {
@@ -342,6 +382,14 @@ var AccessToken = class {
   /**
    * 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, size, expiresIn) {
     let expiresAt;
@@ -359,6 +407,13 @@ var AccessToken = class {
    * 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) {
     const seed = string.random(size);
@@ -417,6 +472,25 @@ var AccessToken = class {
    * is an array of abritary string values
    */
   abilities;
+  /**
+   * 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) {
     this.identifier = attributes.identifier;
     this.tokenableId = attributes.tokenableId;
@@ -441,18 +515,40 @@ var AccessToken = class {
   }
   /**
    * 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) {
     return this.abilities.includes(ability) || this.abilities.includes("*");
   }
   /**
    * 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) {
     return !this.abilities.includes(ability) && !this.abilities.includes("*");
   }
   /**
    * 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) {
     if (this.denies(ability)) {
@@ -465,6 +561,13 @@ var AccessToken = class {
    * date.
    *
    * Tokens with no expiry never expire
+   *
+   * @example
+   * if (token.isExpired()) {
+   *   console.log('Token has expired')
+   * } else {
+   *   console.log('Token is still valid')
+   * }
    */
   isExpired() {
     if (!this.expiresAt) {
@@ -474,11 +577,27 @@ var AccessToken = class {
   }
   /**
    * 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) {
     const newHash = createHash("sha256").update(secret.release()).digest("hex");
     return safeEqual(this.hash, newHash);
   }
+  /**
+   * 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() {
     return {
       type: "bearer",
@@ -536,6 +655,22 @@ var AccessTokensGuard = class {
    * the request is not authenticated.
    */
   user;
+  /**
+   * 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, ctx, emitter, userProvider) {
     this.#name = name;
     this.#ctx = ctx;
@@ -571,6 +706,13 @@ var AccessTokensGuard = class {
   /**
    * 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() {
     if (!this.user) {
@@ -583,6 +725,17 @@ var AccessTokensGuard = class {
   /**
    * 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')
+   * }
    */
   async authenticate() {
     if (this.authenticationAttempted) {
@@ -615,12 +768,27 @@ var AccessTokensGuard = class {
   }
   /**
    * 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())
    */
   async createToken(user, abilities, options) {
     return await this.#userProvider.createToken(user, abilities, options);
   }
   /**
    * Invalidates the currently authenticated token (sign out)
+   *
+   * @example
+   * await guard.invalidateToken()
+   * console.log('Token invalidated successfully')
    */
   async invalidateToken() {
     const bearerToken = new Secret2(this.#getBearerToken());
@@ -629,6 +797,14 @@ var AccessTokensGuard = class {
   /**
    * 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
    */
   async authenticateAsClient(user, abilities, options) {
     const token = await this.#userProvider.createToken(user, abilities, options);
@@ -640,8 +816,15 @@ var AccessTokensGuard = class {
   }
   /**
    * 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)
+   * }
    */
   async check() {
     try {
@@ -660,6 +843,20 @@ var AccessTokensGuard = class {
 import { inspect } from "util";
 import { RuntimeException as RuntimeException2 } from "@adonisjs/core/exceptions";
 var DbAccessTokensProvider = class _DbAccessTokensProvider {
+  /**
+   * 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) {
     this.options = options;
     this.table = options.table || "auth_access_tokens";
@@ -669,6 +866,15 @@ var DbAccessTokensProvider = class _DbAccessTokensProvider {
   }
   /**
    * 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(model, options) {
     return new _DbAccessTokensProvider({ tokenableModel: model, ...options || {} });
@@ -719,7 +925,18 @@ var DbAccessTokensProvider = class _DbAccessTokensProvider {
     }
   }
   /**
-   * 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
+   * })
    */
   dbRowToAccessToken(dbRow) {
     return new AccessToken({
@@ -737,6 +954,10 @@ var DbAccessTokensProvider = class _DbAccessTokensProvider {
   }
   /**
    * Returns a query client instance from the parent model
+   *
+   * @example
+   * const db = await provider.getDb()
+   * const tokens = await db.from('auth_access_tokens').select('*')
    */
   async getDb() {
     const model = this.options.tokenableModel;
@@ -744,6 +965,17 @@ var DbAccessTokensProvider = class _DbAccessTokensProvider {
   }
   /**
    * 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())
    */
   async create(user, abilities = ["*"], options) {
     this.#ensureIsPersisted(user);
@@ -788,6 +1020,15 @@ var DbAccessTokensProvider = class _DbAccessTokensProvider {
   }
   /**
    * 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)
+   * }
    */
   async find(user, identifier) {
     this.#ensureIsPersisted(user);
@@ -800,6 +1041,13 @@ var DbAccessTokensProvider = class _DbAccessTokensProvider {
   }
   /**
    * 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)
    */
   async delete(user, identifier) {
     this.#ensureIsPersisted(user);
@@ -808,7 +1056,14 @@ var DbAccessTokensProvider = class _DbAccessTokensProvider {
     return affectedRows;
   }
   /**
-   * 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))
    */
   async all(user) {
     this.#ensureIsPersisted(user);
@@ -840,6 +1095,14 @@ var DbAccessTokensProvider = class _DbAccessTokensProvider {
    *
    * 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)
+   * }
    */
   async verify(tokenValue) {
     const decodedToken = AccessToken.decode(this.prefix, tokenValue.release());
@@ -861,6 +1124,14 @@ var DbAccessTokensProvider = class _DbAccessTokensProvider {
   }
   /**
    * 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')
+   * }
    */
   async invalidate(tokenValue) {
     const decodedToken = AccessToken.decode(this.prefix, tokenValue.release());
@@ -876,6 +1147,17 @@ var DbAccessTokensProvider = class _DbAccessTokensProvider {
 // modules/access_tokens_guard/user_providers/lucid.ts
 import { RuntimeException as RuntimeException3 } from "@adonisjs/core/exceptions";
 var AccessTokensLucidUserProvider = class {
+  /**
+   * 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(options) {
     this.options = options;
   }
@@ -886,6 +1168,10 @@ var AccessTokensLucidUserProvider = class {
   /**
    * 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)
    */
   async getModel() {
     if (this.model && !("hot" in import.meta)) {
@@ -897,6 +1183,10 @@ var AccessTokensLucidUserProvider = class {
   }
   /**
    * Returns the tokens provider associated with the user model
+   *
+   * @example
+   * const tokensProvider = await provider.getTokensProvider()
+   * const token = await tokensProvider.create(user, ['read'])
    */
   async getTokensProvider() {
     const model = await this.getModel();
@@ -909,6 +1199,13 @@ var AccessTokensLucidUserProvider = class {
   }
   /**
    * 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())
    */
   async createUserForGuard(user) {
     const model = await this.getModel();
@@ -933,6 +1230,17 @@ var AccessTokensLucidUserProvider = class {
   }
   /**
    * 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())
    */
   async createToken(user, abilities, options) {
     const tokensProvider = await this.getTokensProvider();
@@ -940,6 +1248,14 @@ var AccessTokensLucidUserProvider = class {
   }
   /**
    * 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)
    */
   async invalidateToken(tokenValue) {
     const tokensProvider = await this.getTokensProvider();
@@ -947,6 +1263,15 @@ var AccessTokensLucidUserProvider = class {
   }
   /**
    * 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)
+   * }
    */
   async findById(identifier) {
     const model = await this.getModel();
@@ -959,6 +1284,16 @@ var AccessTokensLucidUserProvider = class {
   /**
    * 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)
+   * }
    */
   async verifyToken(tokenValue) {
     const tokensProvider = await this.getTokensProvider();