@aacigroup/aaci_shared 5.3.0 → 5.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +18 -3
- package/dist/types/magicLink.d.ts +13 -2
- package/dist/types/magicLink.d.ts.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -20,8 +20,9 @@ React Context-based tracking and magic-link library for frontend and backend pro
|
|
|
20
20
|
## Features
|
|
21
21
|
|
|
22
22
|
### 🔐 Magic Links & Authentication
|
|
23
|
-
- **V2 Magic Links** with built-in 2FA support (
|
|
23
|
+
- **V2 Magic Links** with built-in 2FA and PIN security support (basic/pin_light/pin_strict/2fa_light/2fa_strict modes)
|
|
24
24
|
- **Email & SMS** 2FA delivery
|
|
25
|
+
- **PIN-based authentication** for enhanced security
|
|
25
26
|
- **Token validation** with URL pattern matching
|
|
26
27
|
- **Admin tokens** for privileged access
|
|
27
28
|
- Full TypeScript support with comprehensive types
|
|
@@ -689,14 +690,16 @@ function MagicLinkExample() {
|
|
|
689
690
|
token,
|
|
690
691
|
current_url: currentUrl,
|
|
691
692
|
mode: 'customer' // or 'admin' for admin access
|
|
693
|
+
// pin: '1234' // Include PIN if security_mode requires it
|
|
692
694
|
});
|
|
693
695
|
|
|
694
696
|
if (result.valid) {
|
|
695
697
|
console.log('Valid! User ID:', result.person_profile_id);
|
|
696
698
|
console.log('Link data:', result.data); // Data stored in magic link data
|
|
699
|
+
console.log('Security mode:', result.security_mode); // 'basic', 'pin_light', etc.
|
|
697
700
|
// Render personalized content
|
|
698
701
|
} else {
|
|
699
|
-
console.log('Invalid:', result.reason); // 'expired', 'revoked', 'url_mismatch', 'not_found'
|
|
702
|
+
console.log('Invalid:', result.reason); // 'expired', 'revoked', 'url_mismatch', 'not_found', 'pin_required', 'pin_invalid'
|
|
700
703
|
}
|
|
701
704
|
};
|
|
702
705
|
|
|
@@ -724,6 +727,7 @@ interface CreateMagicLinkParams {
|
|
|
724
727
|
expires_at?: string; // Optional ISO timestamp
|
|
725
728
|
extra_data?: Record<string, any>; // Optional – stored in magic link data
|
|
726
729
|
session_data?: SessionData; // Optional – auto-populated if not provided
|
|
730
|
+
temp_security_mode?: SecurityMode; // Optional – temporary override for security_mode
|
|
727
731
|
}
|
|
728
732
|
```
|
|
729
733
|
|
|
@@ -742,6 +746,8 @@ interface CreateMagicLinkResponse {
|
|
|
742
746
|
url?: string; // Resolved customer URL
|
|
743
747
|
admin_url?: string; // Resolved admin URL (if admin_url_pattern provided)
|
|
744
748
|
expires_at?: string; // Expiration timestamp (if set)
|
|
749
|
+
security_mode?: SecurityMode; // Security mode applied to this magic link
|
|
750
|
+
pin_code?: string; // PIN code (only returned if security_mode is pin_light or pin_strict)
|
|
745
751
|
message?: string;
|
|
746
752
|
errors?: Array<{ field: string; message: string }>;
|
|
747
753
|
}
|
|
@@ -755,6 +761,7 @@ interface ValidateMagicLinkParams {
|
|
|
755
761
|
token: string; // The token from URL
|
|
756
762
|
current_url: string; // Full URL being accessed
|
|
757
763
|
mode?: 'customer' | 'admin'; // Default: 'customer'
|
|
764
|
+
pin?: string; // PIN code (required if security_mode is pin_light or pin_strict)
|
|
758
765
|
session_data?: SessionData; // Optional – auto-populated if not provided
|
|
759
766
|
}
|
|
760
767
|
```
|
|
@@ -774,11 +781,17 @@ interface ValidateMagicLinkResponse {
|
|
|
774
781
|
magic_link_token_id?: string;
|
|
775
782
|
person_profile_id?: string;
|
|
776
783
|
data?: Record<string, any>; // Data stored in magic link data
|
|
784
|
+
security_mode?: SecurityMode; // Security mode of the magic link
|
|
777
785
|
message?: string;
|
|
778
|
-
reason?: 'expired' | 'revoked' | 'url_mismatch' | 'not_found'; // if invalid
|
|
786
|
+
reason?: 'expired' | 'revoked' | 'url_mismatch' | 'not_found' | 'pin_required' | 'pin_invalid'; // if invalid
|
|
779
787
|
}
|
|
780
788
|
```
|
|
781
789
|
|
|
790
|
+
**SecurityMode Type:**
|
|
791
|
+
```javascript
|
|
792
|
+
type SecurityMode = 'basic' | 'pin_light' | 'pin_strict' | '2fa_light' | '2fa_strict';
|
|
793
|
+
```
|
|
794
|
+
|
|
782
795
|
### Full Page Access Example
|
|
783
796
|
|
|
784
797
|
```javascript
|
|
@@ -855,6 +868,8 @@ function ProtectedSessionPage() {
|
|
|
855
868
|
- **Projects must NOT store tokens** - Only store `magic_link_token_id` in your database entities
|
|
856
869
|
- **Tokens are URL-bound** - A token is only valid when accessed via its designated URL pattern
|
|
857
870
|
- **Tokens are strong** - 32-64 character alphanumeric strings
|
|
871
|
+
- **PIN Security Modes** - When `security_mode` is `pin_light` or `pin_strict`, include the `pin` parameter in validation requests
|
|
872
|
+
- **2FA Security Modes** - When `security_mode` is `2fa_light` or `2fa_strict`, 2FA verification is required before access
|
|
858
873
|
- Your backend should be the single source of truth for token storage and validation
|
|
859
874
|
|
|
860
875
|
## Non-React and Backend Usage
|
|
@@ -11,12 +11,14 @@ export interface CreateMagicLinkParams {
|
|
|
11
11
|
admin_url_pattern?: string;
|
|
12
12
|
expires_at?: string;
|
|
13
13
|
extra_data?: Record<string, any>;
|
|
14
|
+
temp_security_mode?: SecurityMode;
|
|
14
15
|
}
|
|
15
16
|
export interface ValidateMagicLinkParams {
|
|
16
17
|
token: string;
|
|
17
18
|
current_url: string;
|
|
18
19
|
mode?: 'customer' | 'admin';
|
|
19
20
|
twofa?: ValidateMagicLinkV2TwoFAInput;
|
|
21
|
+
pin?: string;
|
|
20
22
|
}
|
|
21
23
|
export interface CreateMagicLinkRequest extends CreateMagicLinkParams {
|
|
22
24
|
project_name: string;
|
|
@@ -33,6 +35,8 @@ export interface CreateMagicLinkResponse {
|
|
|
33
35
|
url?: string;
|
|
34
36
|
admin_url?: string;
|
|
35
37
|
expires_at?: string;
|
|
38
|
+
security_mode?: SecurityMode;
|
|
39
|
+
pin_code?: string;
|
|
36
40
|
message?: string;
|
|
37
41
|
errors?: Array<{
|
|
38
42
|
field: string;
|
|
@@ -46,11 +50,13 @@ export interface ValidateMagicLinkResponse {
|
|
|
46
50
|
magic_link_token_id?: string;
|
|
47
51
|
person_profile_id?: string;
|
|
48
52
|
data?: Record<string, any>;
|
|
53
|
+
security_mode?: SecurityMode;
|
|
49
54
|
message?: string;
|
|
50
|
-
reason?: 'expired' | 'revoked' | 'url_mismatch' | 'not_found' | string;
|
|
55
|
+
reason?: 'expired' | 'revoked' | 'url_mismatch' | 'not_found' | 'pin_required' | 'pin_invalid' | string;
|
|
51
56
|
}
|
|
52
57
|
export type TwoFAMode = 'disabled' | 'light' | 'strict';
|
|
53
58
|
export type TwoFADeliveryMethod = 'email' | 'sms';
|
|
59
|
+
export type SecurityMode = 'basic' | 'pin_light' | 'pin_strict' | '2fa_light' | '2fa_strict';
|
|
54
60
|
export interface CreateMagicLinkV2Request {
|
|
55
61
|
project_name: string;
|
|
56
62
|
email?: string;
|
|
@@ -60,6 +66,7 @@ export interface CreateMagicLinkV2Request {
|
|
|
60
66
|
expires_at?: string;
|
|
61
67
|
extra_data?: Record<string, unknown>;
|
|
62
68
|
session_data?: Record<string, unknown>;
|
|
69
|
+
temp_security_mode?: SecurityMode;
|
|
63
70
|
}
|
|
64
71
|
export interface CreateMagicLinkV2Response {
|
|
65
72
|
status: 'ok' | 'error';
|
|
@@ -73,6 +80,8 @@ export interface CreateMagicLinkV2Response {
|
|
|
73
80
|
twofa_key_code?: string;
|
|
74
81
|
twofa_confirmation_code?: string;
|
|
75
82
|
twofa_valid_until?: string;
|
|
83
|
+
security_mode?: SecurityMode;
|
|
84
|
+
pin_code?: string;
|
|
76
85
|
message?: string;
|
|
77
86
|
errors?: Array<{
|
|
78
87
|
field: string;
|
|
@@ -105,7 +114,7 @@ export interface ConfirmMagicLink2FAResponse {
|
|
|
105
114
|
error_code?: 'invalid_key' | 'invalid_code' | 'expired' | 'already_confirmed' | 'revoked';
|
|
106
115
|
}
|
|
107
116
|
export type ValidateMagicLinkV2Mode = 'customer' | 'admin';
|
|
108
|
-
export type ValidateMagicLinkV2ErrorReason = 'not_found' | 'revoked' | 'expired' | 'url_mismatch' | 'twofa_required' | 'twofa_expired' | 'twofa_invalid_key' | 'twofa_invalid_code' | 'twofa_revoked';
|
|
117
|
+
export type ValidateMagicLinkV2ErrorReason = 'not_found' | 'revoked' | 'expired' | 'url_mismatch' | 'pin_required' | 'pin_invalid' | 'twofa_required' | 'twofa_expired' | 'twofa_invalid_key' | 'twofa_invalid_code' | 'twofa_revoked';
|
|
109
118
|
export interface ValidateMagicLinkV2TwoFAInput {
|
|
110
119
|
key_code: string;
|
|
111
120
|
confirmation_code?: string;
|
|
@@ -116,6 +125,7 @@ export interface ValidateMagicLinkV2Request {
|
|
|
116
125
|
current_url: string;
|
|
117
126
|
mode?: ValidateMagicLinkV2Mode;
|
|
118
127
|
twofa?: ValidateMagicLinkV2TwoFAInput;
|
|
128
|
+
pin?: string;
|
|
119
129
|
session_data?: Record<string, unknown>;
|
|
120
130
|
}
|
|
121
131
|
export interface ValidateMagicLinkV2Response {
|
|
@@ -126,6 +136,7 @@ export interface ValidateMagicLinkV2Response {
|
|
|
126
136
|
person_profile_id?: string;
|
|
127
137
|
data?: Record<string, unknown>;
|
|
128
138
|
twofa_mode?: TwoFAMode;
|
|
139
|
+
security_mode?: SecurityMode;
|
|
129
140
|
reason?: ValidateMagicLinkV2ErrorReason;
|
|
130
141
|
message?: string;
|
|
131
142
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"magicLink.d.ts","sourceRoot":"","sources":["../../src/types/magicLink.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5C,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAGD,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;
|
|
1
|
+
{"version":3,"file":"magicLink.d.ts","sourceRoot":"","sources":["../../src/types/magicLink.ts"],"names":[],"mappings":"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"}
|