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

Trusted Devices

Optional persistent trust for verified browsers.

Optional Persistence

Trusted devices are optional. The authentication controller receives a concrete two-factor-device collection from the ForceSignIn implementation. Without this collection, ordinary TOTP and email 2FA continue to work, but remembered devices are unavailable.

The app-context document inherits user assignment, token hash, expiry and last-used metadata; a concrete application document binds the database collection.

Token Security

The browser receives a cryptographically random token, while persistence stores an HMAC-SHA256 token hash derived using the runtime secret. Validation checks the user assignment and expiry. The standard remembered-device lifetime is 30 days and may be overridden in a concrete ForceSignIn implementation.

Logging out clears the authentication session; it does not automatically revoke a trusted device. Explicit revocation is available through the trusted-device controller.

Public API Reference

Core\User\Auth\TrustedDevices

Class & Registry

Class: Core\User\Auth\TrustedDevices

Extends: Core\User\Auth\TrustedDevices\Base

use Core\User\Auth\TrustedDevices;
use Core\Registry;

$trustedDevices = Registry::get(TrustedDevices::class);
Method Description
public function init(): void Initialize trusted-device controller
public function create( ObjectId|string $userId, int $lifetime ): bool Create trusted device
public function validate(ObjectId|string $userId): bool Validate trusted device
public function revoke(): void Revoke current trusted device
public function cleanup(): int Cleanup expired trusted devices
public function isAvailable(): bool Check if trusted-device functionality is available
public function getToken(): string Get current trusted-device token
public function setCollection(TwoFactorDeviceCollection|null $collection): void Set two-factor device collection
public function getCollection(): TwoFactorDeviceCollection|null Get two-factor device collection

Implementation Details

The following technical reference expands the existing guide with authentication lifecycle, state management, and provider behavior.

Trusted Devices

Overview

Core\User\Auth\TrustedDevice\Base implements persistent trusted-device handling for APPNETOS two-factor authentication.

Trusted devices allow a previously verified browser or device to skip interactive 2FA for a limited period.

The mechanism is provider-independent and works with TOTP, email and future providers.

Architecture

Browser Cookie
→ original random token

Database Document
→ token HMAC hash
→ user ID
→ expiration
→ last-used timestamp

The original token is never stored server-side.

Token Creation

APPNETOS generates:

32 random bytes
→ 256-bit token
→ hexadecimal representation

The server stores only:

HMAC-SHA256(token, runtime secret)

Cookie

The logical cookie key is:

2FA_DEVICE

Physical browser cookie naming and session-scope handling are delegated to:

Core\Cookie

The TrustedDevice controller does not construct physical cookie names.

Default Lifetime

The standard ForceSignIn flow uses approximately:

30 days
2592000 seconds

Applications may override the trusted-device lifetime.

Creation Flow

After successful interactive 2FA:

Remember device selected?
 ├── no → complete authentication
 └── yes
      ↓
   trusted-device collection available?
    ├── no → complete authentication
    └── yes
         ↓
      generate token
         ↓
      store token hash in database
         ↓
      set original token in cookie

Trusted-device availability must never determine whether normal 2FA itself is available.

Validation Flow

Password verified
      ↓
2FA required
      ↓
TrustedDevice available?
      ↓
Read 2FA_DEVICE cookie
      ↓
Hash client token
      ↓
Lookup by:
- user ID
- token hash
- valid expiration
      ↓
Found?
 ├── no
 │    ↓
 │  remove invalid cookie
 │  perform interactive 2FA
 │
 └── yes
      ↓
   expired?
    ├── yes
    │    ↓
    │  delete document
    │  remove cookie
    │  perform interactive 2FA
    │
    └── no
         ↓
      update lastUsedAt
         ↓
      skip interactive 2FA

Revoke

The current device can be revoked by:

  1. Reading the client token.
  2. Hashing it.
  3. Deleting the matching trusted-device document.
  4. Removing the cookie.

Cleanup

Expired trusted-device documents can be removed through the collection cleanup flow.

Security Principles

  • Original token exists only on the client.
  • Server stores deterministic HMAC only.
  • Token belongs to one user.
  • Expiration is explicit.
  • Invalid cookies are removed.
  • Expired documents are rejected.
  • Last-use timestamp is updated after successful validation.
  • Cookie scope is centralized in Core\Cookie.

Next Steps

Previous

TOTP & Email Providers

Explore TOTP & Email Providers

Next

Rendering & UI

Explore Rendering & UI