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

1"""Root hook payload surface for lexigram-auth. 

2 

3Defines canonical payload dataclasses for auth-lifecycle hook points. Actual 

4hook registration and invocation use the framework's string-keyed 

5``HookRegistryProtocol`` action/filter APIs. 

6""" 

7 

8from __future__ import annotations 

9 

10from dataclasses import dataclass 

11 

12__all__ = [ 

13 "AuthAuthenticationFailedHook", 

14 "AuthTokenIssuedHook", 

15 "AuthTokenRefreshedHook", 

16 "AuthTokenRevokedHook", 

17 "AuthUserAuthenticatedHook", 

18] 

19 

20 

21@dataclass(frozen=True, kw_only=True) 

22class AuthUserAuthenticatedHook: 

23 """Payload fired when a user successfully authenticates. 

24 

25 Attributes: 

26 user_id: Identifier of the authenticated user. 

27 method: Authentication method used (e.g. ``"password"``, ``"oauth2"``). 

28 """ 

29 

30 user_id: str 

31 method: str 

32 

33 

34@dataclass(frozen=True, kw_only=True) 

35class AuthAuthenticationFailedHook: 

36 """Payload fired when an authentication attempt fails. 

37 

38 Attributes: 

39 method: Authentication method that was attempted. 

40 reason: Short description of why authentication failed. 

41 """ 

42 

43 method: str 

44 reason: str 

45 

46 

47@dataclass(frozen=True, kw_only=True) 

48class AuthTokenIssuedHook: 

49 """Payload fired when an access or refresh token is issued. 

50 

51 Attributes: 

52 user_id: Identifier of the user the token was issued for. 

53 token_type: Token kind (e.g. ``"access"``, ``"refresh"``). 

54 """ 

55 

56 user_id: str 

57 token_type: str 

58 

59 

60@dataclass(frozen=True, kw_only=True) 

61class AuthTokenRevokedHook: 

62 """Payload fired when a token is explicitly revoked. 

63 

64 Attributes: 

65 user_id: Identifier of the user whose token was revoked. 

66 token_type: Token kind that was revoked. 

67 """ 

68 

69 user_id: str 

70 token_type: str 

71 

72 

73@dataclass(frozen=True, kw_only=True) 

74class AuthTokenRefreshedHook: 

75 """Payload fired when an access token is refreshed. 

76 

77 Attributes: 

78 user_id: Identifier of the user whose token was refreshed. 

79 token_type: Token kind that was refreshed. 

80 """ 

81 

82 user_id: str 

83 token_type: str