@aacigroup/aaci_shared 5.3.1 → 5.3.2

package/README.md

@@ -20,8 +20,9 @@ React Context-based tracking and magic-link library for frontend and backend pro
 ## Features
 
 ### 🔐 Magic Links & Authentication
-- **V2 Magic Links** with built-in 2FA support (light/strict modes)
+- **V2 Magic Links** with built-in 2FA and PIN security support (basic/pin_light/pin_strict/2fa_light/2fa_strict modes)
 - **Email & SMS** 2FA delivery
+- **PIN-based authentication** for enhanced security
 - **Token validation** with URL pattern matching
 - **Admin tokens** for privileged access
 - Full TypeScript support with comprehensive types
@@ -689,14 +690,16 @@ function MagicLinkExample() {
         token,
         current_url: currentUrl,
         mode: 'customer' // or 'admin' for admin access
+        // pin: '1234' // Include PIN if security_mode requires it
       });
 
       if (result.valid) {
         console.log('Valid! User ID:', result.person_profile_id);
         console.log('Link data:', result.data); // Data stored in magic link data
+        console.log('Security mode:', result.security_mode); // 'basic', 'pin_light', etc.
         // Render personalized content
       } else {
-        console.log('Invalid:', result.reason); // 'expired', 'revoked', 'url_mismatch', 'not_found'
+        console.log('Invalid:', result.reason); // 'expired', 'revoked', 'url_mismatch', 'not_found', 'pin_required', 'pin_invalid'
       }
     };
 
@@ -724,6 +727,7 @@ interface CreateMagicLinkParams {
   expires_at?: string;               // Optional ISO timestamp
   extra_data?: Record<string, any>;  // Optional – stored in magic link data
   session_data?: SessionData;        // Optional – auto-populated if not provided
+  temp_security_mode?: SecurityMode; // Optional – temporary override for security_mode
 }
 ```
 
@@ -742,6 +746,8 @@ interface CreateMagicLinkResponse {
   url?: string;                      // Resolved customer URL
   admin_url?: string;                // Resolved admin URL (if admin_url_pattern provided)
   expires_at?: string;               // Expiration timestamp (if set)
+  security_mode?: SecurityMode;      // Security mode applied to this magic link
+  pin_code?: string;                 // PIN code (only returned if security_mode is pin_light or pin_strict)
   message?: string;
   errors?: Array<{ field: string; message: string }>;
 }
@@ -755,6 +761,7 @@ interface ValidateMagicLinkParams {
   token: string;                     // The token from URL
   current_url: string;               // Full URL being accessed
   mode?: 'customer' | 'admin';       // Default: 'customer'
+  pin?: string;                      // PIN code (required if security_mode is pin_light or pin_strict)
   session_data?: SessionData;        // Optional – auto-populated if not provided
 }
 ```
@@ -774,11 +781,17 @@ interface ValidateMagicLinkResponse {
   magic_link_token_id?: string;
   person_profile_id?: string;
   data?: Record<string, any>;        // Data stored in magic link data
+  security_mode?: SecurityMode;      // Security mode of the magic link
   message?: string;
-  reason?: 'expired' | 'revoked' | 'url_mismatch' | 'not_found';  // if invalid
+  reason?: 'expired' | 'revoked' | 'url_mismatch' | 'not_found' | 'pin_required' | 'pin_invalid';  // if invalid
 }
 ```
 
+**SecurityMode Type:**
+```javascript
+type SecurityMode = 'basic' | 'pin_light' | 'pin_strict' | '2fa_light' | '2fa_strict';
+```
+
 ### Full Page Access Example
 
 ```javascript
@@ -855,6 +868,8 @@ function ProtectedSessionPage() {
 - **Projects must NOT store tokens** - Only store `magic_link_token_id` in your database entities
 - **Tokens are URL-bound** - A token is only valid when accessed via its designated URL pattern
 - **Tokens are strong** - 32-64 character alphanumeric strings
+- **PIN Security Modes** - When `security_mode` is `pin_light` or `pin_strict`, include the `pin` parameter in validation requests
+- **2FA Security Modes** - When `security_mode` is `2fa_light` or `2fa_strict`, 2FA verification is required before access
 - Your backend should be the single source of truth for token storage and validation
 
 ## Non-React and Backend Usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aacigroup/aaci_shared",
-  "version": "5.3.1",
+  "version": "5.3.2",
   "description": "Shared tracking utilities for AACI Group projects with React Context support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",