This commit is contained in:
Javier Casares 2026-06-05 16:30:07 +00:00
commit a115f08319

View file

@ -0,0 +1,375 @@
<?php
/**
* Trusted device management.
*
* @package Robotstxt_2FA
*/
namespace Robotstxt\TwoFA\User;
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Manages trusted-device cookies and their server-side records so that users
* can skip the 2FA challenge on browsers they have previously trusted.
*
* Cookie design:
* Name: robotstxt_2fa_trust
* Value: {user_id}|{token_hex}|{hmac_sha256}
* Flags: HttpOnly, Secure (when SSL), SameSite=Strict
*
* Server-side record (user meta robotstxt_2fa_trusted_devices):
* array{ sha256(token) => array{ label: string, created_at: int, expires_at: int } }
*/
class Trusted_Devices {
/**
* User meta key for trusted device records.
*/
private const META_KEY = 'robotstxt_2fa_trusted_devices';
/**
* Cookie name.
*/
public const COOKIE_NAME = 'robotstxt_2fa_trust';
/**
* Maximum stored devices per user.
*/
private const MAX_DEVICES = 10;
/**
* Register hooks.
*
* @since 1.2.0
*
* @return void
*/
public function register_hooks(): void {
add_action( 'robotstxt_2fa_method_enabled', array( $this, 'maybe_clear_on_method_change' ), 10, 2 );
}
/**
* Check whether the current request comes from a trusted device for the given user.
*
* @since 1.2.0
*
* @param \WP_User $user User to check.
*
* @return bool
*/
public function is_trusted( \WP_User $user ): bool {
if ( ! isset( $_COOKIE[ self::COOKIE_NAME ] ) ) {
return false;
}
$cookie_value = is_string( $_COOKIE[ self::COOKIE_NAME ] ) ? $_COOKIE[ self::COOKIE_NAME ] : '';
return $this->verify_cookie( $user, $cookie_value );
}
/**
* Mark the current device as trusted for the given user.
*
* @since 1.2.0
*
* @param \WP_User $user User who trusts the device.
* @param int $days Number of days the trust is valid.
*
* @return void
*/
public function trust_current_device( \WP_User $user, int $days ): void {
if ( $days <= 0 ) {
return;
}
$token = bin2hex( random_bytes( 32 ) );
$expires_at = time() + $days * DAY_IN_SECONDS;
$this->set_cookie( $user->ID, $token, $expires_at );
$this->store_device( $user->ID, $token, $expires_at );
}
/**
* Revoke a specific trusted device by its token hash.
*
* @since 1.2.0
*
* @param int $user_id User ID.
* @param string $token_hash SHA-256 hash of the device token.
*
* @return void
*/
public function revoke( int $user_id, string $token_hash ): void {
$devices = $this->get_raw_devices( $user_id );
unset( $devices[ $token_hash ] );
update_user_meta( $user_id, self::META_KEY, $devices );
}
/**
* Revoke all trusted devices for a user and clear the browser cookie.
*
* @since 1.2.0
*
* @param int $user_id User ID.
*
* @return void
*/
public function revoke_all( int $user_id ): void {
delete_user_meta( $user_id, self::META_KEY );
$this->clear_cookie();
}
/**
* Return the list of active trusted devices for a user.
*
* @since 1.2.0
*
* @param int $user_id User ID.
*
* @return array<string, array{label: string, created_at: int, expires_at: int}>
*/
public function get_devices( int $user_id ): array {
$now = time();
$raw = $this->get_raw_devices( $user_id );
$active = array();
foreach ( $raw as $hash => $entry ) {
if ( is_array( $entry ) && isset( $entry['expires_at'] ) && is_numeric( $entry['expires_at'] ) && (int) $entry['expires_at'] > $now ) {
$active[ $hash ] = array(
'label' => is_string( $entry['label'] ?? null ) ? $entry['label'] : '',
'created_at' => isset( $entry['created_at'] ) && is_int( $entry['created_at'] ) ? $entry['created_at'] : 0,
'expires_at' => (int) $entry['expires_at'],
);
}
}
return $active;
}
/**
* Clear expired device entries for a user (housekeeping).
*
* @since 1.2.0
*
* @param int $user_id User ID.
*
* @return void
*/
public function prune_expired( int $user_id ): void {
$now = time();
$raw = $this->get_raw_devices( $user_id );
$kept = array();
foreach ( $raw as $hash => $entry ) {
if ( is_array( $entry ) && isset( $entry['expires_at'] ) && is_numeric( $entry['expires_at'] ) && (int) $entry['expires_at'] > $now ) {
$kept[ $hash ] = $entry;
}
}
update_user_meta( $user_id, self::META_KEY, $kept );
}
/**
* Optionally clear devices when a user enables a new 2FA method
* (security-conscious sites may want to re-verify all existing sessions).
*
* No-op by default — this method exists as a hook target that site owners
* can swap by removing and re-adding the action with different logic.
*
* @since 1.2.0
*
* @param \WP_User $user User who enabled the method.
* @param string $method Method slug.
*
* @return void
*/
public function maybe_clear_on_method_change( \WP_User $user, string $method ): void {
unset( $method );
// No-op: override via remove_action + add_action to customize behaviour.
}
/**
* Derive a human-readable device label from a User-Agent string.
*
* @since 1.2.0
*
* @param string $ua User-Agent header value.
*
* @return string
*/
public static function label_from_ua( string $ua ): string {
$browser = 'Browser';
$os = 'Unknown OS';
if ( str_contains( $ua, 'Edg/' ) ) {
$browser = 'Edge';
} elseif ( str_contains( $ua, 'Firefox/' ) ) {
$browser = 'Firefox';
} elseif ( str_contains( $ua, 'Chrome/' ) ) {
$browser = 'Chrome';
} elseif ( str_contains( $ua, 'Safari/' ) ) {
$browser = 'Safari';
}
if ( str_contains( $ua, 'iPhone' ) ) {
$os = 'iPhone';
} elseif ( str_contains( $ua, 'iPad' ) ) {
$os = 'iPad';
} elseif ( str_contains( $ua, 'Android' ) ) {
$os = 'Android';
} elseif ( str_contains( $ua, 'Macintosh' ) ) {
$os = 'Mac';
} elseif ( str_contains( $ua, 'Windows' ) ) {
$os = 'Windows';
} elseif ( str_contains( $ua, 'Linux' ) ) {
$os = 'Linux';
}
return "{$browser} on {$os}";
}
/**
* Verify a raw cookie value against the user's stored device records.
*
* @param \WP_User $user User to verify against.
* @param string $cookie_value Raw cookie value.
*
* @return bool
*/
private function verify_cookie( \WP_User $user, string $cookie_value ): bool {
$parts = explode( '|', $cookie_value, 3 );
if ( 3 !== count( $parts ) ) {
return false;
}
[ $user_id_raw, $token, $sig ] = $parts;
if ( absint( $user_id_raw ) !== $user->ID ) {
return false;
}
if ( ! defined( 'AUTH_SALT' ) || '' === AUTH_SALT ) {
return false;
}
$expected_sig = hash_hmac( 'sha256', $user->ID . '|' . $token, AUTH_SALT );
if ( ! hash_equals( $expected_sig, $sig ) ) {
return false;
}
$token_hash = hash( 'sha256', $token );
$devices = $this->get_raw_devices( $user->ID );
if ( ! isset( $devices[ $token_hash ] ) || ! is_array( $devices[ $token_hash ] ) ) {
return false;
}
$entry = $devices[ $token_hash ];
return isset( $entry['expires_at'] ) && is_numeric( $entry['expires_at'] ) && (int) $entry['expires_at'] > time();
}
/**
* Write the trust cookie to the browser.
*
* @param int $user_id User ID.
* @param string $token Plain-text token (hex).
* @param int $expires_at Unix timestamp when the trust expires.
*
* @return void
*/
private function set_cookie( int $user_id, string $token, int $expires_at ): void {
if ( ! defined( 'AUTH_SALT' ) || '' === AUTH_SALT ) {
return;
}
$sig = hash_hmac( 'sha256', $user_id . '|' . $token, AUTH_SALT );
$value = $user_id . '|' . $token . '|' . $sig;
setcookie(
self::COOKIE_NAME,
$value,
array(
'expires' => $expires_at,
'path' => defined( 'COOKIEPATH' ) ? COOKIEPATH : '/',
'domain' => defined( 'COOKIE_DOMAIN' ) ? COOKIE_DOMAIN : '',
'secure' => is_ssl(),
'httponly' => true,
'samesite' => 'Strict',
)
);
}
/**
* Clear the trust cookie from the browser.
*
* @return void
*/
private function clear_cookie(): void {
setcookie(
self::COOKIE_NAME,
'',
array(
'expires' => time() - YEAR_IN_SECONDS,
'path' => defined( 'COOKIEPATH' ) ? COOKIEPATH : '/',
'domain' => defined( 'COOKIE_DOMAIN' ) ? COOKIE_DOMAIN : '',
'secure' => is_ssl(),
'httponly' => true,
'samesite' => 'Strict',
)
);
}
/**
* Persist a new device record in user meta.
*
* @param int $user_id User ID.
* @param string $token Plain-text token.
* @param int $expires_at Expiry timestamp.
*
* @return void
*/
private function store_device( int $user_id, string $token, int $expires_at ): void {
$devices = $this->get_raw_devices( $user_id );
$ua = isset( $_SERVER['HTTP_USER_AGENT'] ) && is_string( $_SERVER['HTTP_USER_AGENT'] ) ? $_SERVER['HTTP_USER_AGENT'] : ''; // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- used only for label display.
$label = self::label_from_ua( sanitize_text_field( $ua ) );
$devices[ hash( 'sha256', $token ) ] = array(
'label' => $label,
'created_at' => time(),
'expires_at' => $expires_at,
);
// Keep only the most recent MAX_DEVICES entries.
if ( count( $devices ) > self::MAX_DEVICES ) {
uasort(
$devices,
static function ( mixed $a, mixed $b ): int {
$a_ts = is_array( $a ) && isset( $a['created_at'] ) && is_int( $a['created_at'] ) ? $a['created_at'] : 0;
$b_ts = is_array( $b ) && isset( $b['created_at'] ) && is_int( $b['created_at'] ) ? $b['created_at'] : 0;
return $b_ts <=> $a_ts; // Newest first.
}
);
$devices = array_slice( $devices, 0, self::MAX_DEVICES, true );
}
update_user_meta( $user_id, self::META_KEY, $devices );
}
/**
* Retrieve the raw device map from user meta.
*
* @param int $user_id User ID.
*
* @return array<string, mixed>
*/
private function get_raw_devices( int $user_id ): array {
$raw = get_user_meta( $user_id, self::META_KEY, true );
return is_array( $raw ) ? $raw : array();
}
}