TOTP & Email Providers
TOTP and email verification providers.
TOTP Provider
The TOTP provider follows RFC 6238-compatible time-based verification. Defaults are a six-digit code, a 30-second time step and a ±1-step verification window. Secrets are generated using cryptographically secure random bytes, and provisioning URIs can be rendered as SVG QR codes through the QR code component.
Email Provider
Email 2FA requires a usable and fully configured mail transport supplied by the concrete provider implementation. The shared email provider base is unavailable until a mailer is supplied and its usability is confirmed. The default challenge is a six-digit numeric code valid for 600 seconds.
The authentication layer generates and HMAC-hashes codes, sends the email, tracks challenge expiry
and
limits attempts. ForceSignIn only manages the HTTP and UI workflow. An unavailable
mailer
or failed send must not silently bypass 2FA.
Public API Reference
Core\User\Auth\TwoFactor\Provider\Totp
Class & Registry
Class:
Core\User\Auth\TwoFactor\Provider\Totp
Extends:
Core\User\Auth\TwoFactor\Provider\Totp\Base
use Core\User\Auth\TwoFactor\Provider\Totp;
use Core\Registry;
$totp = Registry::get(Totp::class);
| Method | Description |
|---|---|
public function init(): void |
Initialize TOTP provider |
public function verify( UserDocument $userDocument, string $code ):
bool
|
Verify two-factor authentication code |
public function verifySecret( string $secret, string $code ): bool |
Verify two-factor authentication code by secret |
public function generateSecret(int $bytes = 20): string |
Generate TOTP secret |
public function isInitialized(UserDocument $userDocument): bool |
Check if TOTP authentication is initialized |
public function getProvisioningUri( UserDocument $userDocument, string
$issuer,
string|null $account = null ): string|null |
Get TOTP provisioning URI |
public function getProvisioningUriBySecret( string $secret, string $issuer,
string
$account ): string|null |
Get TOTP provisioning URI by secret |
public function getQrCode( UserDocument $userDocument, string $issuer,
string|null
$account = null ): string|null |
Get TOTP QR code |
public function getQrCodeBySecret( string $secret, string $issuer, string
$account
):
string|null |
Get TOTP QR code by secret |
Core\User\Auth\TwoFactor\Provider\Email
Class & Registry
Class:
Core\User\Auth\TwoFactor\Provider\Email
Extends:
Core\User\Auth\TwoFactor\Provider\Email\Base
use Core\User\Auth\TwoFactor\Provider\Email;
use Core\Registry;
$email = Registry::get(Email::class);
| Method | Description |
|---|---|
public function init(): void |
Initialize email two-factor authentication provider |
public function isAvailable(): bool |
Check email two-factor authentication availability |
public function generateCode(): string |
Generate email authentication code |
public function hashCode(string $code): string |
Hash email authentication code |
public function verifyCode( string $code, string $hash ): bool |
Verify email authentication code hash |
public function verify( UserDocument $userDocument, string $code ):
bool
|
Verify email authentication code |
public function send( UserDocument $userDocument, string $code ): bool
|
Send email authentication code |
public function getCodeLifetime(): int |
Get authentication-code lifetime |
Core\User\Auth\TwoFactor\Provider
Class & Registry
Class:
Core\User\Auth\TwoFactor\Provider
Extends:
Core\User\Auth\TwoFactor\Provider\Base
use Core\User\Auth\TwoFactor\Provider;
use Core\Registry;
$provider = Registry::get(Provider::class);
| Method | Description |
|---|---|
public function verify( UserDocument $userDocument, string $code ):
bool
|
Verify two-factor authentication code |
Implementation Details
The following technical reference expands the existing guide with authentication lifecycle, state management, and provider behavior.
TOTP
Overview
Core\User\Auth\TwoFactor\Provider\Totp\Base implements RFC6238-compatible Time-Based
One-Time Password authentication.
Defaults
digits = 6
period = 30 seconds
window = 1
algorithm = SHA1
Secret Format
TOTP secrets use Base32 encoding.
Secrets are generated from cryptographically secure random bytes.
Default:
20 random bytes
→ Base32 encoded secret
Verification
The provider:
- Loads the user's persisted TOTP secret.
- Normalizes the submitted code.
- Validates the expected code length.
- Calculates the current time slice.
- Checks the configured tolerance window.
- Uses constant-time comparison with
hash_equals().
Validation Window
With:
window = 1
APPNETOS checks:
previous time slice
current time slice
next time slice
This compensates for small clock differences between the server and authenticator device.
Code Generation
TOTP code generation uses:
Base32 secret
→ binary secret
→ HMAC-SHA1
→ dynamic truncation
→ modulo 10^digits
→ zero-padded code
Provisioning URI
The provider generates standard otpauth:// URIs:
otpauth://totp/{issuer}:{account}
?secret={secret}
&issuer={issuer}
&algorithm=SHA1
&digits=6
&period=30
QR Code
QR-code rendering is delegated to:
Core\QrCode
Flow:
TOTP secret
→ provisioning URI
→ Core\QrCode
→ SVG QR code
No temporary image file is required.
Initialization Detection
A user is considered initialized for TOTP when a non-empty TOTP secret is persisted on the user document.
TOTP Enrollment
Overview
Initial TOTP enrollment uses temporary authentication-session state.
A TOTP secret must never be persisted merely because a QR code was displayed.
Why Temporary Enrollment State Is Required
Persisting the secret before verification would create a half-initialized user:
QR displayed
→ user closes browser
→ persisted secret remains
→ authenticator was never proven to be configured
APPNETOS avoids this by keeping the secret temporary until the user submits a valid first TOTP code.
Enrollment Flow
Password verified
↓
2FA required
↓
Provider = TOTP
↓
Persisted secret exists?
├── yes → normal TOTP verification
└── no
↓
Generate temporary secret
↓
Store secret in auth session
↓
Generate provisioning URI
↓
Generate QR code
↓
User scans QR code
↓
User submits first TOTP code
↓
Verify against temporary secret
↓
Valid?
├── no → remain pending
└── yes
↓
Persist secret on user document
↓
Complete 2FA
Temporary State
The authentication session stores:
provider
secret
setup time
Lifetime
Default setup lifetime:
600 seconds
10 minutes
The authentication child may override:
protected function getTwoFactorSetupLifetime(): int
{
return 600;
}
Starting Enrollment
Core\User\Auth\Base::startTotpSetup():
- Resolves the pending user.
- Confirms TOTP is the pending provider.
- Confirms no persistent secret exists.
- Resolves issuer and account.
- Reuses valid temporary setup state.
- Removes expired setup state.
- Generates a new secret when required.
- Stores the secret only in the auth session.
- Generates provisioning URI.
- Generates SVG QR code.
Return structure:
[
'secret' => $secret,
'provisioning_uri' => $provisioningUri,
'qr_code' => $qrCode,
]
Completing Enrollment
completeTotpSetup() verifies the first code against the temporary secret.
Only after successful verification:
temporary secret
→ user.twoFactorSecret
→ persist user
→ optional trusted device
→ complete auth session
→ assign runtime user
Email Two-Factor Authentication
Overview
APPNETOS email two-factor authentication uses a temporary numeric challenge delivered through the shared APPNETOS Mailer.
The provider is implemented by:
Core\User\Auth\TwoFactor\Provider\Email\Base
The complete workflow is orchestrated by:
Core\User\Auth\Base
Core\User\Auth\Session\Base
Context-Specific Mailer Configuration
The shared email provider never decides whether app or admin mailer settings are used.
Mapped runtime children provide:
protected function getMailer(): array|null
and:
protected function getMailerUsable(): bool
This keeps the shared provider context-independent.
Challenge Flow
Password verified
↓
2FA required
↓
Provider = email
↓
Mailer usable?
├── no
│ ↓
│ authentication remains pending
│ technical error shown
│
└── yes
↓
Generate 6-digit code
↓
Create HMAC-SHA256 hash
↓
Store hash + challenge metadata
↓
Send original code through Mailer
↓
Mail sent?
├── no
│ ↓
│ challenge removed
│ resend remains possible
│
└── yes
↓
render code input
↓
verify submitted code
↓
valid?
├── no → increment attempts
└── yes
↓
optional trusted device
↓
complete authentication
Code Generation
Default code length:
6 digits
Generation uses random_int() and preserves leading zeros.
Example valid code:
004731
Hashing
The clear authentication code is not persisted.
APPNETOS creates a deterministic:
HMAC-SHA256
using the APPNETOS runtime secret.
Session state stores only the hash.
Challenge State
The authentication session stores:
codeHash
createdAt
expiresAt
attempts
The clear code exists only during generation, mail delivery and user submission.
Lifetime
Default email challenge lifetime:
600 seconds
10 minutes
After expiration, verification fails and the challenge is cleared.
Maximum Attempts
Default:
5 invalid attempts
After the maximum is reached, the active challenge is invalidated.
Resend
Resending creates a new challenge.
old challenge
→ removed
new code
→ generated
new hash
→ stored
new email
→ sent
The previous code becomes invalid immediately.
Idempotent Initial Rendering
Repeated rendering or browser refreshes do not automatically generate a new email while a valid challenge already exists.
This prevents unnecessary repeated authentication emails.
Delivery Errors
APPNETOS distinguishes two states.
Mailer unavailable
email provider configured
mailer not usable
Result:
no code input
no successful challenge
technical error
Mailer available but send failed
Result:
no code input
challenge removed
resend action available
Security Properties
- Clear code is never persisted.
- Challenge is temporary.
- Hash uses runtime secret.
- Verification uses constant-time comparison.
- Attempts are limited.
- Expired challenges are rejected.
- Resend invalidates the old code.
- Configured email 2FA is never silently bypassed.