feat: add conditional auth actions

[memleakd]

Description

This PR adds a small opt-in way for auth actions to decide whether they apply to a specific user.

The idea came from the earlier MFA/2FA discussions and stalled work around Shield.

• feat: add allow to cancel actions for custom cases #324
• 2FA for Specific User Group(s) #1120
• feat: expand 2FA support #1254

This is the first small piece: actions can implement ConditionalActionInterface and return true or false from appliesTo(User $user). That makes cases like "require an action only for admins" possible without changing existing actions or forcing every app into the same policy.

final class AdminEmail2FA extends Email2FA implements ConditionalActionInterface
{
    public function appliesTo(User $user): bool
    {
        return $user->inGroup('admin', 'superadmin');
    }
}

Existing actions keep working as before. If an action does not implement the new interface, Shield treats it as always applicable.

A couple of edge cases are handled intentionally:

• If a conditional action does not apply, Shield skips starting it and ignores stored identities for that action.
• If a user is already inactive and has a stored activation identity, Shield still requires activation. This avoids turning conditional activation into a way around activation.
• If an action is already pending in the session, Shield continues that pending action instead of rechecking the condition mid-flow.

This should give Shield a safer foundation for future MFA work, while keeping this PR focused on the existing auth action system.

Tests cover login actions, registration activation, stored action identities, magic-link activation, and session filter behavior.

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value
• Unit testing, with >80% coverage
• User guide updated
• Conforms to style guide

[datamweb]

Hi @memleakd! This feature looks absolutely fantastic, and I really want to thank you for the clean and solid implementation. The simple and straightforward example you provided in the description is great and makes the concept very easy to understand.

However, what is hidden inside this PR is another fascinating and powerful capability that could be even more practical. As we know, Shield currently has an architectural limitation where only one class (a linear action) can be defined for each event in the config ($actions array). It seems your PR is exactly the key to bypassing this limitation!

With this new ConditionalActionInterface, it becomes entirely possible to build a class like a TwoFactorGatewayAction. Consider a scenario where a user(end user) has configured both SMS 2FA and Email 2FA methods:

We could register this Gateway as the single action for the login event. Using the appliesTo() method, we check if the user has any active methods. If they do, this Gateway can act as a Router. Instead of forcing a static method, it can render a View during login, giving the user the choice of how to receive their code (SMS or Email). This practically resolves Shield’s single-action limitation.

I haven’t had the time to fully implement and test this specific Gateway scenario myself, but architecturally, it makes perfect sense.

I wanted to ask you to look into this aspect of your feature as well. If you can verify that it works for such combined scenarios to bypass Shield’s limitations, I highly recommend documenting this advanced pattern thoroughly in a new section of the docs (perhaps under the Guides or Customization sections). This would be a massive added value for developers who need to handle more complex scenarios.

Thanks again for this clean architecture and valuable PR. Excellent work!

[memleakd]

Thank you so much @datamweb, you honestly made my day with this!

I really like the gateway-style action idea. I think you’re right that this PR can help with that pattern, especially by giving the gateway the missing applicability check: it can decide whether it should run for a user at all.

The actual routing between methods, like SMS vs Email, would still live inside the action’s show() / handle() / verify() flow. Because of that, I think it would be better as a focused follow-up PR once the pattern is implemented and tested properly.

For this PR I tried to keep the scope small and focused on the foundation, but I'll be very happy to explore the gateway pattern right after this lands.

[datamweb]

I’m really glad to hear that.
LGTM!