1	<?php
2
3	/**
4	* This program is free software; you can redistribute it and/or
5	* modify it under the terms of the GNU General Public License
6	* as published by the Free Software Foundation; under version 2
7	* of the License (non-upgradable).
8	*
9	* This program is distributed in the hope that it will be useful,
10	* but WITHOUT ANY WARRANTY; without even the implied warranty of
11	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12	* GNU General Public License for more details.
13	*
14	* You should have received a copy of the GNU General Public License
15	* along with this program; if not, write to the Free Software
16	* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
17	*
18	* Copyright (c) 2018 (original work) Open Assessment Technologies SA (under the project TAO-PRODUCT);
19	*/
20
21	namespace oat\tao\model\user;
22
23	use oat\oatbox\user\User;
24	use oat\tao\model\event\LoginFailedEvent;
25	use oat\tao\model\event\LoginSucceedEvent;
26
27	/**
28	* Interface UserLocks
29	* This interface describe how should be implemented service that follows failed user logons
30	* and locks them permanently or temporary.
31	* @package oat\tao\model\user
32	*/
33	interface UserLocks
34	{
35	public const SERVICE_ID = 'tao/userlocks';
36
37	/** Use hard lock for failed logon. Be default soft lock will be used */
38	public const OPTION_USE_HARD_LOCKOUT = 'use_hard_lockout';
39
40	/** Amount of failed login attempts before lockout */
41	public const OPTION_LOCKOUT_FAILED_ATTEMPTS = 'lockout_failed_attempts';
42
43	/** Duration of soft lock out */
44	public const OPTION_SOFT_LOCKOUT_PERIOD = 'soft_lockout_period';
45
46	/** List of roles whose users can not be blocked */
47	public const OPTION_NON_LOCKING_ROLES = 'non_locking_roles';
48
49	/**
50	* Event listener that catches failed login events and makes decision to lock user or not
51	* @param LoginFailedEvent $event
52	* @throws \core_kernel_users_Exception
53	*/
54	public function catchFailedLogin(LoginFailedEvent $event);
55
56	/**
57	* Event listener that catches succeed login events and makes decision to unlock user or not
58	* @param LoginSucceedEvent $event
59	* @throws \core_kernel_users_Exception
60	*/
61	public function catchSucceedLogin(LoginSucceedEvent $event);
62
63	/**
64	* Locks user by another user (administrator)
65	* @param $user
66	* @return mixed
67	*/
68	public function lockUser(User $user);
69
70	/**
71	* Unlocks user
72	* @param $user
73	* @return mixed
74	*/
75	public function unlockUser(User $user);
76
77	/**
78	* Returns true if user is locked else false
79	* @param $login
80	* @return bool
81	* @throws \core_kernel_users_Exception
82	*/
83	public function isLocked($login);
84
85	/**
86	* Returns true if user can be locked
87	* @param $user
88	* @return mixed
89	*/
90	public function isLockable(User $user);
91
92	/**
93	* Returns remaining time that left before user will be unlocked
94	* @param $login
95	* @return mixed
96	* @throws \core_kernel_users_Exception
97	*/
98	public function getLockoutRemainingTime($login);
99
100	/**
101	* Returns remaining attempts that left before user will be locked
102	* @param $login
103	* @return mixed
104	* @throws \core_kernel_users_Exception
105	*/
106	public function getLockoutRemainingAttempts($login);
107
108	/**
109	* Returns detailed information about user account status
110	* @param $login
111	* @return array
112	*   boolean        array.locked - returns true if user is locked else false
113	*   boolean        array.auto - returns true if user auto locked (locked by himself) else false
114	*   string         array.status - human readable string with actual account status
115	*   DateInterval   array.remaining - returns valid period of time that left before user will be unlocked, may be
116	*                                    null if not applicable
117	*   boolean        array.lockable - returns true if user can be locked else false
118	* @throws \core_kernel_users_Exception
119	*/
120	public function getStatusDetails($login);
121	}