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 User MFA Device and Authentication Credential Management.
13 *
14 * Manages multi-device enrollment, TOTP verification with anti-replay,
15 * SVG QR code presentation, and single-use emergency recovery codes.
16 *
17 * @package App\Modules\User\Application\Service
18 */
19interface UserMfaDeviceServiceInterface
20{
21    /**
22     * Checks if user has at least one active enrolled MFA device.
23     *
24     * @param int $userId User ID.
25     * @return bool True if MFA is enabled and active.
26     */
27    public function hasActiveMfa(int $userId): bool;
28
29    /**
30     * Returns list of user's registered MFA devices.
31     *
32     * @param int $userId User ID.
33     * @return array<int, array<string, mixed>> List of device descriptors.
34     */
35    public function getUserDevices(int $userId): array;
36
37    /**
38     * Initiates new authenticator device enrollment session.
39     *
40     * @param int $userId User ID.
41     * @param string $deviceName Device label.
42     * @param string $issuer App issuer name.
43     * @return array{secret: string, otpauth_uri: string, qr_svg: string, device_name: string}
44     */
45    public function startEnrollment(int $userId, string $deviceName, string $issuer = 'Ammonly'): array;
46
47    /**
48     * Confirms and activates new authenticator device after verifying user-supplied TOTP code.
49     *
50     * @param int $userId User ID.
51     * @param string $deviceName Device label.
52     * @param string $secret Plaintext Base32 secret.
53     * @param string $verificationCode 6-digit TOTP code.
54     * @return array{success: bool, recovery_codes?: array<int, string>, message?: string}
55     */
56    public function confirmEnrollment(
57        int $userId,
58        string $deviceName,
59        string $secret,
60        string $verificationCode
61    ): array;
62
63    /**
64     * Revokes an existing MFA device.
65     *
66     * @param int $userId User ID.
67     * @param int $deviceId Target device ID.
68     * @return bool True on success.
69     */
70    public function revokeDevice(int $userId, int $deviceId): bool;
71
72    /**
73     * Sets an active device as primary default authenticator.
74     *
75     * @param int $userId User ID.
76     * @param int $deviceId Target device ID.
77     * @return bool True on success, false if device not found or inactive.
78     */
79    public function setDefaultDevice(int $userId, int $deviceId): bool;
80
81    /**
82     * Returns default authenticator device descriptor for user.
83     *
84     * @param int $userId User ID.
85     * @return array<string, mixed>|null Default device descriptor or null if none.
86     */
87    public function getDefaultDevice(int $userId): ?array;
88
89    /**
90     * Verifies TOTP code or emergency recovery code during user authentication.
91     *
92     * @param int $userId User ID.
93     * @param string $code 6-digit TOTP code or 10-character recovery code.
94     * @return bool True if valid, false otherwise.
95     */
96    public function verifyUserMfa(int $userId, string $code): bool;
97}
98