v1.2.0
This commit is contained in:
parent
d405d8587d
commit
a115f08319
1 changed files with 1817 additions and 141 deletions
375
includes/user/class-trusted-devices.php
Normal file
375
includes/user/class-trusted-devices.php
Normal 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();
|
||||
}
|
||||
}
|
||||
Loading…
Reference in a new issue