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:
- Reading the client token.
- Hashing it.
- Deleting the matching trusted-device document.
- 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.