Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
1 / 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\Modules\User\Application\Service;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11/**
12 * Interface for OWASP ASVS & NIST SP 800-63B Compliant Password Reset Service.
13 *
14 * Enforces anti-enumeration semantics, cryptographically secure 256-bit token hashes,
15 * strict 15-minute NTP-adjusted expiration windows, session termination, and multi-language emails.
16 *
17 * @package App\Modules\User\Application\Service
18 */
19interface PasswordResetServiceInterface
20{
21    /**
22     * Initiates password reset request for given username or email.
23     *
24     * Always returns success message to prevent user enumeration attacks.
25     *
26     * @param string $loginOrEmail User login identifier or registered email.
27     * @param string $ipAddress Client IP address.
28     * @param string $userAgent Client user agent string.
29     * @param string $appBaseUrl Application base URL for link construction.
30     * @param string $requestLocale Active user interface locale code (e.g. 'pl', 'en').
31     * @return array{success: bool, message: string} Outcome response.
32     */
33    public function requestPasswordReset(
34        string $loginOrEmail,
35        string $ipAddress,
36        string $userAgent,
37        string $appBaseUrl,
38        string $requestLocale = 'pl'
39    ): array;
40
41    /**
42     * Validates cryptographic raw token against database hash and NTP expiration.
43     *
44     * @param string $rawToken Plaintext token from URL query parameter.
45     * @return array{valid: bool, user_id?: int, email?: string, username?: string, error?: string} Validation outcome.
46     */
47    public function validateToken(string $rawToken): array;
48
49    /**
50     * Consumes valid token and securely updates user password.
51     *
52     * Enforces NIST password strength rules, marks token used, revokes active sessions,
53     * and sends confirmation notification in user's preferred language.
54     *
55     * @param string $rawToken Plaintext token.
56     * @param string $newPassword New password chosen by user.
57     * @param string $ipAddress Client IP address.
58     * @param string $userAgent Client user agent string.
59     * @return array{success: bool, message: string} Operation result.
60     */
61    public function completePasswordReset(
62        string $rawToken,
63        string $newPassword,
64        string $ipAddress,
65        string $userAgent
66    ): array;
67}