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\Core\Security\Mfa;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11/**
12 * Interface for Multi-Factor Authentication (MFA) TOTP Engine.
13 *
14 * Implements RFC 6238 / RFC 4226 TOTP standards, multi-device key management,
15 * anti-replay protection, and cryptographic single-use recovery codes.
16 *
17 * @package App\Core\Security\Mfa
18 */
19interface MfaTotpServiceInterface
20{
21    /**
22     * Generates a cryptographically secure Base32-encoded secret key.
23     *
24     * @param int $byteLength Secret entropy in bytes (default 20 bytes = 160 bits).
25     * @return string Base32-encoded secret.
26     */
27    public function generateSecret(int $byteLength = 20): string;
28
29    /**
30     * Computes the TOTP code for a given secret and authoritative timestamp.
31     *
32     * @param string $secret Base32-encoded secret.
33     * @param int|null $timestamp Optional timestamp (defaults to adjusted NTP time).
34     * @param int $digits Number of output digits (default 6).
35     * @param int $period Time step in seconds (default 30).
36     * @param string $algorithm Hash algorithm: sha1, sha256 (default sha1).
37     * @return string Zero-padded TOTP code.
38     */
39    public function calculateCode(
40        string $secret,
41        ?int $timestamp = null,
42        int $digits = 6,
43        int $period = 30,
44        string $algorithm = 'sha1'
45    ): string;
46
47    /**
48     * Verifies TOTP code against secret with anti-replay protection.
49     *
50     * @param string $code 6-digit user-submitted code.
51     * @param string $secret Base32 secret.
52     * @param int|null $lastUsedStep Previous verified time step to prevent replay.
53     * @param int $window Tolerance steps (+/- window, default 1).
54     * @param int $period Time step in seconds (default 30).
55     * @param string $algorithm Hash algorithm.
56     * @return int|null Matched time step if valid, null on verification failure.
57     */
58    public function verifyCode(
59        string $code,
60        string $secret,
61        ?int $lastUsedStep = null,
62        int $window = 1,
63        int $period = 30,
64        string $algorithm = 'sha1'
65    ): ?int;
66
67    /**
68     * Builds standard otpauth URI for QR code generation and mobile authenticators.
69     *
70     * @param string $accountName User identifier or email.
71     * @param string $secret Base32 secret.
72     * @param string $issuer Application or organization name.
73     * @param int $digits Digits count.
74     * @param int $period Time step in seconds.
75     * @param string $algorithm Hash algorithm.
76     * @return string Standard otpauth://totp/... URI.
77     */
78    public function buildOtpAuthUri(
79        string $accountName,
80        string $secret,
81        string $issuer = 'Ammonly',
82        int $digits = 6,
83        int $period = 30,
84        string $algorithm = 'sha1'
85    ): string;
86
87    /**
88     * Generates a batch of cryptographically secure single-use recovery codes.
89     *
90     * @param int $count Number of recovery codes to generate (default 8).
91     * @return array<int, string> Plaintext recovery codes.
92     */
93    public function generateRecoveryCodes(int $count = 8): array;
94
95    /**
96     * Encrypts plaintext Base32 secret for persistent database storage.
97     *
98     * @param string $secret Plaintext Base32 secret.
99     * @return string Authenticated encrypted string.
100     */
101    public function encryptSecret(string $secret): string;
102
103    /**
104     * Decrypts encrypted Base32 secret from database.
105     *
106     * @param string $encrypted Encrypted payload.
107     * @return string Plaintext Base32 secret.
108     */
109    public function decryptSecret(string $encrypted): string;
110}