[Potential PR/ suggestion] Why is the Rehash password feature (and some others) only exist in the SessionGuard?

[Lumethys]

For context, I'm working on a hobby project which would offer multiple authentication schemes for API (which would include cookies, long-lived access token, jwt - refresh token combo,...) since the credentials check is the same and just what to return differs.

Basically I wanted feature parity for all the schemes, but I can't help but notice that some features, namely rehash password, and timebox to prevent side channel timing attacks, only exist in the SessionGuard, which implement the StatefulGuard interface.

examining the Auth::attempt() method:

1. The attempt event is fired
2. An Authenticable object is retrieved by the provider and set the the $lastAttempted variable
3. Check the credential against the Authenticable object in a Timebox
4. Rehash password if configured
5. login (which will handle session, set the user, fire the Login and Authenticated events,...)

I can see that 3. and 4. doesn't exist on the TokenGuard, or the RequestGuard, even though for the rehash password, the implementation actually comes from the UserProvider, and both features conceptually doesn't really need to be stateful

This had a couple of problems that I can see:

1. There are a lot of invisible imparity between the StatefulGuard (SessionGuard) and the regular Guard (TokenGuard and RequestGuard) beyond statefulness vs statelessness
2. TokenGuard is effectively non-existent in the docs (even the "supported driver" section in config/auth.php), if it is deprecated, it should be warned so in the docs
3. RequestGuard, which is still in use and recommended in the docs, with Auth::viaRequest() will be unable to utilize these features

Bonus: I'm aware that all token based approaches is recommended to go through Sanctum or Passport, and Sanctum do use SessionGuard under the hood. And there exists the Auth::once() method to do stateless auth with the session driver. But:

1. Sanctum docs doesnt mention or recommend the Auth facade, nor mention or notice about these features, particularly the Mobile Login section, which recommend just User::where() and Hash::check(), at the very least, it should mention the use of Timebox to Guard against timing attack or should rehash the password on login. Or they should just recommend Auth::once()
2. Speaking of Timebox, there is no documentation on it, either how to interact with or what to do with it.
3. Speaking of Auth::once(), it is not currently emit the Illuminate\Auth\Events\Failed event (via fireFailedEvent()) as oppose to Auth::attempt(), or Auth::attemptWhen(). Unsure if this is oversight or there is deeper reason I am unaware of.
4. Speaking of Auth::attemptWhen(), there is no Auth::onceWhen() equivalent of Auth::once()
5. Speaking of Auth::attempt() and Auth::attemptWhen(), you can just call Auth::attemptWhen() inside Auth::attempt() with callback: null
6. Although all the Guards had the Macroable trait, the docs had no information on how to use them, currently i am just extending the SessionGuard and register it as a new custom guard

I am open to contribute some PRs myself, but I want to see if any of the points I raise had some deeper reasons that I am not aware of.

To summary, there is some potential improvement:

1. Add these features to the stateless Guards, or even to the interfaces
2. Mark TokenGuard as deprecated (?)
3. Fire Failed event on Auth::once()
4. Add new Auth::onceWhen() method
5. Write docs for the TimeBox
6. Improve docs on the timing attacks and rehash password on login attempts, particularly the Sanctum Mobile Auth.

[hafezdivandari]

Related to laravel/passport#1743