@aacigroup/aaci_shared 5.3.1 → 5.3.3

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/dist/index.d.ts

@@ -8,7 +8,7 @@ export { Environment } from './Environment.js';
 export { getSessionData } from './sessionData.js';
 export { validateTrackLeadParams, validateAddress, validateTrackLeadAndAddress, safeValidateTrackLeadParams, safeValidateAddress, safeValidateTrackLeadAndAddress, validateCreateMagicLinkParams, validateValidateMagicLinkParams, safeValidateCreateMagicLinkParams, safeValidateValidateMagicLinkParams, validateCreateMagicLinkRequest, validateValidateMagicLinkRequest, safeValidateCreateMagicLinkRequest, safeValidateValidateMagicLinkRequest, validateCreateMagicLinkV2Request, safeValidateCreateMagicLinkV2Request, validateCreateMagicLink2FAV2Request, safeValidateCreateMagicLink2FAV2Request, validateValidateMagicLinkV2Request, safeValidateValidateMagicLinkV2Request, validateConfirmMagicLink2FARequest, safeValidateConfirmMagicLink2FARequest, validateSendExternalNotificationRequest, safeValidateSendExternalNotificationRequest, trackLeadParamsSchema, addressSchema, addressInputSchema, trackLeadAndAddressSchema, sessionDataSchema, createMagicLinkParamsSchema, validateMagicLinkParamsSchema, createMagicLinkRequestSchema, validateMagicLinkRequestSchema, createMagicLinkV2RequestSchema, createMagicLink2FAV2RequestSchema, validateMagicLinkV2RequestSchema, confirmMagicLink2FARequestSchema, twoFAModeSchema, twoFADeliveryMethodSchema, externalNotificationChannelSchema, sendExternalNotificationRequestSchema } from './validation.js';
 export type { Lead, AddressCapture, SessionData, TrackLeadParams, Address, AddressInput, LeadTrackerConfig, TrackingConfig, LeadTrackingResponse } from './types.js';
-export type { MagicLinkConfig, CreateMagicLinkParams, ValidateMagicLinkParams, CreateMagicLinkRequest, ValidateMagicLinkRequest, CreateMagicLinkResponse, ValidateMagicLinkResponse, TwoFAMode, TwoFADeliveryMethod, CreateMagicLinkV2Request, CreateMagicLinkV2Response, CreateMagicLink2FAV2Request, CreateMagicLink2FAV2Response, ValidateMagicLinkV2Mode, ValidateMagicLinkV2ErrorReason, ValidateMagicLinkV2TwoFAInput, ValidateMagicLinkV2Request, ValidateMagicLinkV2Response, ConfirmMagicLink2FARequest, ConfirmMagicLink2FAResponse, Create2FAParams, Create2FAResponse, Confirm2FAParams, Confirm2FAResponse } from './types/magicLink.js';
+export type { MagicLinkConfig, CreateMagicLinkParams, ValidateMagicLinkParams, CreateMagicLinkRequest, ValidateMagicLinkRequest, CreateMagicLinkResponse, ValidateMagicLinkResponse, TwoFAMode, TwoFADeliveryMethod, SecurityMode, CreateMagicLinkV2Request, CreateMagicLinkV2Response, CreateMagicLink2FAV2Request, CreateMagicLink2FAV2Response, ValidateMagicLinkV2Mode, ValidateMagicLinkV2ErrorReason, ValidateMagicLinkV2TwoFAInput, ValidateMagicLinkV2Request, ValidateMagicLinkV2Response, ConfirmMagicLink2FARequest, ConfirmMagicLink2FAResponse, Create2FAParams, Create2FAResponse, Confirm2FAParams, Confirm2FAResponse } from './types/magicLink.js';
 export type { ExternalNotificationChannel, ExternalNotificationStatus, SendExternalNotificationRequest, SendExternalNotificationResponse } from './types/externalNotification.js';
 export type { PostHogConfig } from './PostHog.js';
 export type { GTMConfig } from './GTM.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,KAAK,YAAmD,CAAC;AAGtE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,2BAA2B,EAC3B,2BAA2B,EAC3B,mBAAmB,EACnB,+BAA+B,EAE/B,6BAA6B,EAC7B,+BAA+B,EAC/B,iCAAiC,EACjC,mCAAmC,EAEnC,8BAA8B,EAC9B,gCAAgC,EAChC,kCAAkC,EAClC,oCAAoC,EAEpC,gCAAgC,EAChC,oCAAoC,EACpC,mCAAmC,EACnC,uCAAuC,EACvC,kCAAkC,EAClC,sCAAsC,EACtC,kCAAkC,EAClC,sCAAsC,EAEtC,uCAAuC,EACvC,2CAA2C,EAE3C,qBAAqB,EACrB,aAAa,EACb,kBAAkB,EAClB,yBAAyB,EACzB,iBAAiB,EACjB,2BAA2B,EAC3B,6BAA6B,EAC7B,4BAA4B,EAC5B,8BAA8B,EAE9B,8BAA8B,EAC9B,iCAAiC,EACjC,gCAAgC,EAChC,gCAAgC,EAChC,eAAe,EACf,yBAAyB,EAEzB,iCAAiC,EACjC,qCAAqC,EACtC,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EAEV,IAAI,EACJ,cAAc,EACd,WAAW,EAGX,eAAe,EACf,OAAO,EACP,YAAY,EAGZ,iBAAiB,EACjB,cAAc,EAGd,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,wBAAwB,EACxB,uBAAuB,EACvB,yBAAyB,EAEzB,SAAS,EACT,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EACzB,2BAA2B,EAC3B,4BAA4B,EAC5B,uBAAuB,EACvB,8BAA8B,EAC9B,6BAA6B,EAC7B,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAE3B,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAG9B,YAAY,EACV,2BAA2B,EAC3B,0BAA0B,EAC1B,+BAA+B,EAC/B,gCAAgC,EACjC,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EACV,aAAa,EACd,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,SAAS,EACV,MAAM,UAAU,CAAC;AAElB,YAAY,EACV,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,0BAA0B,EAC3B,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,KAAK,YAAmD,CAAC;AAGtE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,2BAA2B,EAC3B,2BAA2B,EAC3B,mBAAmB,EACnB,+BAA+B,EAE/B,6BAA6B,EAC7B,+BAA+B,EAC/B,iCAAiC,EACjC,mCAAmC,EAEnC,8BAA8B,EAC9B,gCAAgC,EAChC,kCAAkC,EAClC,oCAAoC,EAEpC,gCAAgC,EAChC,oCAAoC,EACpC,mCAAmC,EACnC,uCAAuC,EACvC,kCAAkC,EAClC,sCAAsC,EACtC,kCAAkC,EAClC,sCAAsC,EAEtC,uCAAuC,EACvC,2CAA2C,EAE3C,qBAAqB,EACrB,aAAa,EACb,kBAAkB,EAClB,yBAAyB,EACzB,iBAAiB,EACjB,2BAA2B,EAC3B,6BAA6B,EAC7B,4BAA4B,EAC5B,8BAA8B,EAE9B,8BAA8B,EAC9B,iCAAiC,EACjC,gCAAgC,EAChC,gCAAgC,EAChC,eAAe,EACf,yBAAyB,EAEzB,iCAAiC,EACjC,qCAAqC,EACtC,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EAEV,IAAI,EACJ,cAAc,EACd,WAAW,EAGX,eAAe,EACf,OAAO,EACP,YAAY,EAGZ,iBAAiB,EACjB,cAAc,EAGd,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,wBAAwB,EACxB,uBAAuB,EACvB,yBAAyB,EAEzB,SAAS,EACT,mBAAmB,EACnB,YAAY,EACZ,wBAAwB,EACxB,yBAAyB,EACzB,2BAA2B,EAC3B,4BAA4B,EAC5B,uBAAuB,EACvB,8BAA8B,EAC9B,6BAA6B,EAC7B,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAE3B,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAG9B,YAAY,EACV,2BAA2B,EAC3B,0BAA0B,EAC1B,+BAA+B,EAC/B,gCAAgC,EACjC,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EACV,aAAa,EACd,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,SAAS,EACV,MAAM,UAAU,CAAC;AAElB,YAAY,EACV,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,0BAA0B,EAC3B,MAAM,2BAA2B,CAAC"}

package/package.json

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