APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

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:

  1. Loads the user's persisted TOTP secret.
  2. Normalizes the submitted code.
  3. Validates the expected code length.
  4. Calculates the current time slice.
  5. Checks the configured tolerance window.
  6. 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():

  1. Resolves the pending user.
  2. Confirms TOTP is the pending provider.
  3. Confirms no persistent secret exists.
  4. Resolves issuer and account.
  5. Reuses valid temporary setup state.
  6. Removes expired setup state.
  7. Generates a new secret when required.
  8. Stores the secret only in the auth session.
  9. Generates provisioning URI.
  10. 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.

Next Steps

Previous

Two-Factor Authentication

Explore Two-Factor Authentication

Next

Trusted Devices

Explore Trusted Devices