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 */ 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' ) || ! is_string( 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' ) || ! is_string( 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' ) && is_string( 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' ) && is_string( 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. * * Non-string keys (corrupted meta) are discarded so callers always * receive a token-hash-keyed map. * * @param int $user_id User ID. * * @return array */ private function get_raw_devices( int $user_id ): array { $raw = get_user_meta( $user_id, self::META_KEY, true ); if ( ! is_array( $raw ) ) { return array(); } return array_filter( $raw, 'is_string', ARRAY_FILTER_USE_KEY ); } }