Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00%
0 / 1
n/a
0 / 0
 CRAP
n/a
0 / 0
1<?php
2
3declare(strict_types=1);
4
5/** @license For full copyright and license information, please see the LICENSE.md file. */
6
7namespace App\Core\Security\StepUp;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use Yiisoft\Session\SessionInterface;
12
13/**
14 * Re-Authentication (Step-Up) Service Interface.
15 *
16 * Enforces NIST SP 800-63B ยง7.2 and OWASP ASVS v5 V3.7.1 requiring users to re-authenticate
17 * before executing sensitive administrative or security-critical transactions.
18 *
19 * @package App\Core\Security\StepUp
20 */
21interface ReAuthenticationServiceInterface
22{
23    /** @var int Default maximum authentication freshness threshold in seconds (10 minutes). */
24    public const int DEFAULT_FRESHNESS_WINDOW = 600;
25
26    /**
27     * Checks if the active session has recently authenticated within the freshness window.
28     *
29     * @param SessionInterface $session Active session instance.
30     * @param int              $maxAgeSeconds Maximum permitted age in seconds.
31     * @return bool True if session is fresh, false otherwise.
32     */
33    public function hasFreshAuth(SessionInterface $session, int $maxAgeSeconds = self::DEFAULT_FRESHNESS_WINDOW): bool;
34
35    /**
36     * Marks the active session as freshly authenticated with the current timestamp.
37     *
38     * @param SessionInterface $session Active session instance.
39     * @return void
40     */
41    public function markFreshAuth(SessionInterface $session): void;
42
43    /**
44     * Verifies user password and updates freshness timestamp if correct.
45     *
46     * @param int              $userId   User identifier.
47     * @param string           $password Plaintext candidate password.
48     * @param SessionInterface $session  Active session instance.
49     * @return bool True if password is valid and freshness was updated, false otherwise.
50     */
51    public function verifyAndRefresh(int $userId, string $password, SessionInterface $session): bool;
52}