Coverage for src/lexigram/auth/events.py: 100%

1"""Auth domain events emitted by key authentication operations. 

2 

3Consumers subscribe via :class:`~lexigram.contracts.events.protocols.EventBusProtocol`. 

4All events inherit from :class:`~lexigram.contracts.domain.events.DomainEvent` and carry 

5``event_id``, ``occurred_at``, and optional event-sourcing metadata from the base. 

6""" 

7 

8from __future__ import annotations 

9 

10from dataclasses import dataclass 

11 

12from lexigram.contracts.domain.events import DomainEvent 

13 

14 

15@dataclass(frozen=True, init=False) 

16class UserAuthenticated(DomainEvent): 

17 """Emitted when a user successfully authenticates. 

18 

19 Attributes: 

20 user_id: ID of the authenticated user. 

21 method: Authentication method used (e.g. ``"password"``). 

22 ip: Remote IP address of the request, if available. 

23 """ 

24 

25 user_id: str 

26 method: str 

27 ip: str | None = None 

28 

29 

30@dataclass(frozen=True, init=False) 

31class AuthenticationFailed(DomainEvent): 

32 """Emitted when an authentication attempt fails. 

33 

34 Attributes: 

35 email: Email that was used in the failed attempt. 

36 reason: Human-readable reason for the failure. 

37 ip: Remote IP address of the request, if available. 

38 """ 

39 

40 email: str 

41 reason: str 

42 ip: str | None = None 

43 

44 

45@dataclass(frozen=True, init=False) 

46class UserRegistered(DomainEvent): 

47 """Emitted when a new user account is created. 

48 

49 Attributes: 

50 user_id: ID of the newly created user. 

51 email: Email address of the newly created user. 

52 """ 

53 

54 user_id: str 

55 email: str 

56 

57 

58@dataclass(frozen=True, init=False) 

59class PasswordChanged(DomainEvent): 

60 """Emitted when a user successfully changes their password. 

61 

62 Attributes: 

63 user_id: ID of the user whose password was changed. 

64 """ 

65 

66 user_id: str 

67 

68 

69@dataclass(frozen=True, init=False) 

70class SessionCreated(DomainEvent): 

71 """Emitted when a new session/token is issued. 

72 

73 Attributes: 

74 session_id: Identifier for the new session. 

75 user_id: ID of the user who owns the session. 

76 """ 

77 

78 session_id: str 

79 user_id: str 

80 

81 

82@dataclass(frozen=True, init=False) 

83class SessionRevoked(DomainEvent): 

84 """Emitted when a session/token is invalidated. 

85 

86 Attributes: 

87 session_id: Identifier of the revoked session. 

88 user_id: ID of the user who owned the session. 

89 """ 

90 

91 session_id: str 

92 user_id: str 

93 

94 

95# --------------------------------------------------------------------------- 

96# High-fidelity login lifecycle events (G4-A12.2) 

97# --------------------------------------------------------------------------- 

98 

99 

100@dataclass(frozen=True, init=False) 

101class UserLoggedIn(DomainEvent): 

102 """Emitted after a successful password-based login. 

103 

104 Attributes: 

105 user_id: ID of the authenticated user. 

106 email: Email address used to log in. 

107 """ 

108 

109 user_id: str 

110 email: str 

111 

112 

113@dataclass(frozen=True, init=False) 

114class UserLoginFailed(DomainEvent): 

115 """Emitted when a login attempt fails due to bad credentials. 

116 

117 Attributes: 

118 email: Email address used in the failed attempt. 

119 reason: Human-readable reason for the failure. 

120 """ 

121 

122 email: str 

123 reason: str 

124 

125 

126@dataclass(frozen=True, init=False) 

127class UserLockedOut(DomainEvent): 

128 """Emitted when a login attempt is rejected because the account is locked. 

129 

130 Attributes: 

131 user_id: ID of the locked-out user. 

132 email: Email address of the locked-out user. 

133 """ 

134 

135 user_id: str 

136 email: str 

137 

138 

139@dataclass(frozen=True, init=False) 

140class UserLoggedOut(DomainEvent): 

141 """Emitted when a user explicitly logs out. 

142 

143 Attributes: 

144 user_id: ID of the user who logged out. 

145 """ 

146 

147 user_id: str 

148 

149 

150@dataclass(frozen=True, init=False) 

151class TokenRevoked(DomainEvent): 

152 """Emitted when a specific token is revoked. 

153 

154 Attributes: 

155 token_id: JTI or opaque identifier of the revoked token. 

156 user_id: ID of the user who owned the token. 

157 reason: Human-readable reason for revocation. 

158 """ 

159 

160 token_id: str 

161 user_id: str 

162 reason: str 

163 

164 

165__all__ = [ 

166 "AuthenticationFailed", 

167 "PasswordChanged", 

168 "SessionCreated", 

169 "SessionRevoked", 

170 "TokenRevoked", 

171 "UserAuthenticated", 

172 "UserLockedOut", 

173 "UserLoggedIn", 

174 "UserLoggedOut", 

175 "UserLoginFailed", 

176 "UserRegistered", 

177]