@adonisjs/auth 9.5.0 → 10.0.0-next.0

package/build/modules/session_guard/main.js

@@ -1,130 +1,10 @@
 import {
   E_UNAUTHORIZED_ACCESS
-} from "../../chunk-MUPAP5IP.js";
+} from "../../chunk-S5G5RTJX.js";
 import "../../chunk-UXA4FHST.js";
 
-// modules/session_guard/remember_me_token.ts
-import { createHash } from "crypto";
-import string from "@adonisjs/core/helpers/string";
-import { Secret, base64, safeEqual } from "@adonisjs/core/helpers";
-var RememberMeToken = class {
-  /**
-   * Decodes a publicly shared token and return the series
-   * and the token value from it.
-   *
-   * Returns null when unable to decode the token because of
-   * invalid format or encoding.
-   */
-  static decode(value) {
-    if (typeof value !== "string") {
-      return null;
-    }
-    if (!value) {
-      return null;
-    }
-    const [identifier, ...tokenValue] = value.split(".");
-    if (!identifier || tokenValue.length === 0) {
-      return null;
-    }
-    const decodedIdentifier = base64.urlDecode(identifier);
-    const decodedSecret = base64.urlDecode(tokenValue.join("."));
-    if (!decodedIdentifier || !decodedSecret) {
-      return null;
-    }
-    return {
-      identifier: decodedIdentifier,
-      secret: new Secret(decodedSecret)
-    };
-  }
-  /**
-   * Creates a transient token that can be shared with the persistence
-   * layer.
-   */
-  static createTransientToken(userId, size, expiresIn) {
-    const expiresAt = /* @__PURE__ */ new Date();
-    expiresAt.setSeconds(expiresAt.getSeconds() + string.seconds.parse(expiresIn));
-    return {
-      userId,
-      expiresAt,
-      ...this.seed(size)
-    };
-  }
-  /**
-   * Creates a secret opaque token and its hash.
-   */
-  static seed(size) {
-    const seed = string.random(size);
-    const secret = new Secret(seed);
-    const hash = createHash("sha256").update(secret.release()).digest("hex");
-    return { secret, hash };
-  }
-  /**
-   * Identifer is a unique sequence to identify the
-   * token within database. It should be the
-   * primary/unique key
-   */
-  identifier;
-  /**
-   * Reference to the user id for whom the token
-   * is generated.
-   */
-  tokenableId;
-  /**
-   * The value is a public representation of a token. It is created
-   * by combining the "identifier"."secret"
-   */
-  value;
-  /**
-   * Hash is computed from the seed to later verify the validity
-   * of seed
-   */
-  hash;
-  /**
-   * Date/time when the token instance was created
-   */
-  createdAt;
-  /**
-   * Date/time when the token was updated
-   */
-  updatedAt;
-  /**
-   * Timestamp at which the token will expire
-   */
-  expiresAt;
-  constructor(attributes) {
-    this.identifier = attributes.identifier;
-    this.tokenableId = attributes.tokenableId;
-    this.hash = attributes.hash;
-    this.createdAt = attributes.createdAt;
-    this.updatedAt = attributes.updatedAt;
-    this.expiresAt = attributes.expiresAt;
-    if (attributes.secret) {
-      this.value = new Secret(
-        `${base64.urlEncode(String(this.identifier))}.${base64.urlEncode(
-          attributes.secret.release()
-        )}`
-      );
-    }
-  }
-  /**
-   * Check if the token has been expired. Verifies
-   * the "expiresAt" timestamp with the current
-   * date.
-   */
-  isExpired() {
-    return this.expiresAt < /* @__PURE__ */ new Date();
-  }
-  /**
-   * Verifies the value of a token against the pre-defined hash
-   */
-  verify(secret) {
-    const newHash = createHash("sha256").update(secret.release()).digest("hex");
-    return safeEqual(this.hash, newHash);
-  }
-};
-
 // modules/session_guard/guard.ts
-import { Secret as Secret2 } from "@adonisjs/core/helpers";
+import { Secret } from "@adonisjs/core/helpers";
 import { RuntimeException } from "@adonisjs/core/exceptions";
 var SessionGuard = class {
   /**
@@ -191,16 +71,40 @@ var SessionGuard = class {
   /**
    * The key used to store the logged-in user id inside
    * session
+   *
+   * @example
+   * console.log('Session key:', guard.sessionKeyName) // 'auth_web'
    */
   get sessionKeyName() {
     return `auth_${this.#name}`;
   }
   /**
    * The key used to store the remember me token cookie
+   *
+   * @example
+   * console.log('Remember me key:', guard.rememberMeKeyName) // 'remember_web'
    */
   get rememberMeKeyName() {
     return `remember_${this.#name}`;
   }
+  /**
+   * 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, ctx, options, emitter, userProvider) {
     this.#name = name;
     this.#ctx = ctx;
@@ -312,7 +216,7 @@ var SessionGuard = class {
    */
   async #authenticateViaRememberCookie(rememberMeCookie, sessionId) {
     const userProvider = this.#userProvider;
-    const token = await userProvider.verifyRememberToken(new Secret2(rememberMeCookie));
+    const token = await userProvider.verifyRememberToken(new Secret(rememberMeCookie));
     if (!token) {
       throw this.#authenticationFailed(sessionId);
     }
@@ -385,7 +289,7 @@ var SessionGuard = class {
     this.#ctx.response.clearCookie(this.rememberMeKeyName);
     if (this.user && rememberMeCookie && this.#options.useRememberMeTokens) {
       const userProvider = this.#userProvider;
-      const token = await userProvider.verifyRememberToken(new Secret2(rememberMeCookie));
+      const token = await userProvider.verifyRememberToken(new Secret(rememberMeCookie));
       if (token) {
         await userProvider.deleteRemeberToken(this.user, token.identifier);
       }
@@ -457,10 +361,196 @@ var SessionGuard = class {
   }
 };
 
+// modules/session_guard/remember_me_token.ts
+import { createHash } from "crypto";
+import string from "@adonisjs/core/helpers/string";
+import { Secret as Secret2, base64, safeEqual } from "@adonisjs/core/helpers";
+var RememberMeToken = class {
+  /**
+   * Decodes a publicly shared token and return the series
+   * and the token value from it.
+   *
+   * Returns null when unable to decode the token because of
+   * invalid format or encoding.
+   *
+   * @param value - The token value to decode
+   *
+   * @example
+   * const decoded = RememberMeToken.decode('abc123.def456')
+   * if (decoded) {
+   *   console.log('Token ID:', decoded.identifier)
+   *   console.log('Secret:', decoded.secret.release())
+   * }
+   */
+  static decode(value) {
+    if (typeof value !== "string") {
+      return null;
+    }
+    if (!value) {
+      return null;
+    }
+    const [identifier, ...tokenValue] = value.split(".");
+    if (!identifier || tokenValue.length === 0) {
+      return null;
+    }
+    const decodedIdentifier = base64.urlDecode(identifier);
+    const decodedSecret = base64.urlDecode(tokenValue.join("."));
+    if (!decodedIdentifier || !decodedSecret) {
+      return null;
+    }
+    return {
+      identifier: decodedIdentifier,
+      secret: new Secret2(decodedSecret)
+    };
+  }
+  /**
+   * 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 - Expiration time (seconds or duration string)
+   *
+   * @example
+   * const transientToken = RememberMeToken.createTransientToken(123, 32, '30d')
+   * // Store transientToken in database
+   */
+  static createTransientToken(userId, size, expiresIn) {
+    const expiresAt = /* @__PURE__ */ new Date();
+    expiresAt.setSeconds(expiresAt.getSeconds() + string.seconds.parse(expiresIn));
+    return {
+      userId,
+      expiresAt,
+      ...this.seed(size)
+    };
+  }
+  /**
+   * Creates a secret opaque token and its hash.
+   *
+   * @param size - The size of the random string to generate
+   *
+   * @example
+   * const { secret, hash } = RememberMeToken.seed(32)
+   * console.log('Secret:', secret.release())
+   * console.log('Hash:', hash)
+   */
+  static seed(size) {
+    const seed = string.random(size);
+    const secret = new Secret2(seed);
+    const hash = createHash("sha256").update(secret.release()).digest("hex");
+    return { secret, hash };
+  }
+  /**
+   * Identifer is a unique sequence to identify the
+   * token within database. It should be the
+   * primary/unique key
+   */
+  identifier;
+  /**
+   * Reference to the user id for whom the token
+   * is generated.
+   */
+  tokenableId;
+  /**
+   * The value is a public representation of a token. It is created
+   * by combining the "identifier"."secret"
+   */
+  value;
+  /**
+   * Hash is computed from the seed to later verify the validity
+   * of seed
+   */
+  hash;
+  /**
+   * Date/time when the token instance was created
+   */
+  createdAt;
+  /**
+   * Date/time when the token was updated
+   */
+  updatedAt;
+  /**
+   * Timestamp at which the token will expire
+   */
+  expiresAt;
+  /**
+   * Creates a new RememberMeToken instance
+   *
+   * @param attributes - Token attributes including identifier, user ID, hash, etc.
+   *
+   * @example
+   * const token = new RememberMeToken({
+   *   identifier: 1,
+   *   tokenableId: 123,
+   *   hash: 'sha256hash',
+   *   createdAt: new Date(),
+   *   updatedAt: new Date(),
+   *   expiresAt: new Date(Date.now() + 86400000)
+   * })
+   */
+  constructor(attributes) {
+    this.identifier = attributes.identifier;
+    this.tokenableId = attributes.tokenableId;
+    this.hash = attributes.hash;
+    this.createdAt = attributes.createdAt;
+    this.updatedAt = attributes.updatedAt;
+    this.expiresAt = attributes.expiresAt;
+    if (attributes.secret) {
+      this.value = new Secret2(
+        `${base64.urlEncode(String(this.identifier))}.${base64.urlEncode(
+          attributes.secret.release()
+        )}`
+      );
+    }
+  }
+  /**
+   * Check if the token has been expired. Verifies
+   * the "expiresAt" timestamp with the current
+   * date.
+   *
+   * @example
+   * if (token.isExpired()) {
+   *   console.log('Remember me token has expired')
+   * } else {
+   *   console.log('Token is still valid')
+   * }
+   */
+  isExpired() {
+    return this.expiresAt < /* @__PURE__ */ new Date();
+  }
+  /**
+   * 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('Remember me token is valid')
+   * }
+   */
+  verify(secret) {
+    const newHash = createHash("sha256").update(secret.release()).digest("hex");
+    return safeEqual(this.hash, newHash);
+  }
+};
+
 // modules/session_guard/token_providers/db.ts
 import { inspect } from "util";
 import { RuntimeException as RuntimeException2 } from "@adonisjs/core/exceptions";
 var DbRememberMeTokensProvider = class _DbRememberMeTokensProvider {
+  /**
+   * Creates a new DbRememberMeTokensProvider instance
+   *
+   * @param options - Configuration options for the provider
+   *
+   * @example
+   * const provider = new DbRememberMeTokensProvider({
+   *   tokenableModel: () => import('#models/user'),
+   *   table: 'remember_me_tokens',
+   *   tokenSecretLength: 40
+   * })
+   */
   constructor(options) {
     this.options = options;
     this.table = options.table || "remember_me_tokens";
@@ -468,6 +558,15 @@ var DbRememberMeTokensProvider = class _DbRememberMeTokensProvider {
   }
   /**
    * Create tokens provider instance for a given Lucid model
+   *
+   * @param model - The tokenable model factory function
+   * @param options - Optional configuration options
+   *
+   * @example
+   * const provider = DbRememberMeTokensProvider.forModel(
+   *   () => import('#models/user'),
+   *   { table: 'user_remember_tokens' }
+   * )
    */
   static forModel(model, options) {
     return new _DbRememberMeTokensProvider({
@@ -509,6 +608,16 @@ var DbRememberMeTokensProvider = class _DbRememberMeTokensProvider {
   }
   /**
    * Maps a database row to an instance token instance
+   *
+   * @param dbRow - The database row containing token data
+   *
+   * @example
+   * const token = provider.dbRowToRememberMeToken({
+   *   id: 1,
+   *   tokenable_id: 123,
+   *   hash: 'sha256hash',
+   *   // ... other columns
+   * })
    */
   dbRowToRememberMeToken(dbRow) {
     return new RememberMeToken({
@@ -522,6 +631,10 @@ var DbRememberMeTokensProvider = class _DbRememberMeTokensProvider {
   }
   /**
    * Returns a query client instance from the parent model
+   *
+   * @example
+   * const db = await provider.getDb()
+   * const tokens = await db.from('remember_me_tokens').select('*')
    */
   async getDb() {
     const model = this.options.tokenableModel;
@@ -529,6 +642,13 @@ var DbRememberMeTokensProvider = class _DbRememberMeTokensProvider {
   }
   /**
    * Create a token for a user
+   *
+   * @param user - The user instance to create a token for
+   * @param expiresIn - Token expiration time
+   *
+   * @example
+   * const token = await provider.create(user, '30d')
+   * console.log('Remember token:', token.value.release())
    */
   async create(user, expiresIn) {
     this.#ensureIsPersisted(user);
@@ -564,6 +684,15 @@ var DbRememberMeTokensProvider = class _DbRememberMeTokensProvider {
   }
   /**
    * 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 with id:', token.identifier)
+   * }
    */
   async find(user, identifier) {
     this.#ensureIsPersisted(user);
@@ -576,6 +705,13 @@ var DbRememberMeTokensProvider = class _DbRememberMeTokensProvider {
   }
   /**
    * 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);
@@ -585,6 +721,13 @@ var DbRememberMeTokensProvider = class _DbRememberMeTokensProvider {
   }
   /**
    * Returns all the tokens 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, 'remember tokens')
+   * tokens.forEach(token => console.log(token.identifier))
    */
   async all(user) {
     this.#ensureIsPersisted(user);
@@ -600,6 +743,14 @@ var DbRememberMeTokensProvider = class _DbRememberMeTokensProvider {
    *
    * 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('rmt_abc123.def456'))
+   * if (token && !token.isExpired()) {
+   *   console.log('Valid remember token for user:', token.tokenableId)
+   * }
    */
   async verify(tokenValue) {
     const decodedToken = RememberMeToken.decode(tokenValue.release());
@@ -624,6 +775,14 @@ var DbRememberMeTokensProvider = class _DbRememberMeTokensProvider {
    * Ideally, the recycle should update the existing token, but we
    * skip that for now and come back to it later and handle race
    * conditions as well.
+   *
+   * @param user - The user that owns the token
+   * @param identifier - The token identifier to recycle
+   * @param expiresIn - New expiration time
+   *
+   * @example
+   * const newToken = await provider.recycle(user, 123, '30d')
+   * console.log('Recycled token:', newToken.value.release())
    */
   async recycle(user, identifier, expiresIn) {
     await this.delete(user, identifier);
@@ -634,6 +793,16 @@ var DbRememberMeTokensProvider = class _DbRememberMeTokensProvider {
 // modules/session_guard/user_providers/lucid.ts
 import { RuntimeException as RuntimeException3 } from "@adonisjs/core/exceptions";
 var SessionLucidUserProvider = class {
+  /**
+   * Creates a new SessionLucidUserProvider instance
+   *
+   * @param options - Configuration options for the user provider
+   *
+   * @example
+   * const provider = new SessionLucidUserProvider({
+   *   model: () => import('#models/user')
+   * })
+   */
   constructor(options) {
     this.options = options;
   }
@@ -644,6 +813,10 @@ var SessionLucidUserProvider = 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)) {
@@ -655,6 +828,10 @@ var SessionLucidUserProvider = class {
   }
   /**
    * Returns the tokens provider associated with the user model
+   *
+   * @example
+   * const tokensProvider = await provider.getTokensProvider()
+   * const token = await tokensProvider.create(user, '7d')
    */
   async getTokensProvider() {
     const model = await this.getModel();
@@ -667,6 +844,13 @@ var SessionLucidUserProvider = 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();
@@ -691,6 +875,15 @@ var SessionLucidUserProvider = class {
   }
   /**
    * Finds a user by their primary key value
+   *
+   * @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();
@@ -702,6 +895,13 @@ var SessionLucidUserProvider = class {
   }
   /**
    * Creates a remember token for a given user
+   *
+   * @param user - The user to create a token for
+   * @param expiresIn - Token expiration time
+   *
+   * @example
+   * const token = await provider.createRememberToken(user, '30d')
+   * console.log('Remember token:', token.value.release())
    */
   async createRememberToken(user, expiresIn) {
     const tokensProvider = await this.getTokensProvider();
@@ -709,6 +909,16 @@ var SessionLucidUserProvider = class {
   }
   /**
    * Verify a token by its publicly shared value
+   *
+   * @param tokenValue - The token value to verify
+   *
+   * @example
+   * const token = await provider.verifyRememberToken(
+   *   new Secret('rmt_abc123.def456')
+   * )
+   * if (token && !token.isExpired()) {
+   *   console.log('Valid remember token for user:', token.tokenableId)
+   * }
    */
   async verifyRememberToken(tokenValue) {
     const tokensProvider = await this.getTokensProvider();
@@ -716,6 +926,13 @@ var SessionLucidUserProvider = class {
   }
   /**
    * Delete a token for a user by the token identifier
+   *
+   * @param user - The user that owns the token
+   * @param identifier - The token identifier to delete
+   *
+   * @example
+   * const deletedCount = await provider.deleteRemeberToken(user, 123)
+   * console.log('Deleted tokens:', deletedCount)
    */
   async deleteRemeberToken(user, identifier) {
     const tokensProvider = await this.getTokensProvider();
@@ -723,6 +940,14 @@ var SessionLucidUserProvider = class {
   }
   /**
    * Recycle a token for a user by the token identifier
+   *
+   * @param user - The user that owns the token
+   * @param identifier - The token identifier to recycle
+   * @param expiresIn - New expiration time
+   *
+   * @example
+   * const newToken = await provider.recycleRememberToken(user, 123, '30d')
+   * console.log('Recycled token:', newToken.value.release())
    */
   async recycleRememberToken(user, identifier, expiresIn) {
     const tokensProvider = await this.getTokensProvider();