@payez/next-mvp 4.8.0 → 4.8.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.
Files changed (301) hide show
  1. package/POST-INSTALL.md +408 -408
  2. package/README.md +859 -859
  3. package/dist/components/account/MobileNavDrawer.js +18 -18
  4. package/dist/components/account/UserAvatarMenu.js +1 -1
  5. package/dist/components/admin/AlertSettingsTab.js +40 -40
  6. package/dist/components/admin/LoggingSettingsTab.js +28 -28
  7. package/dist/lib/session-store.js +21 -21
  8. package/dist/lib/startup-init.js +19 -19
  9. package/dist/middleware/create-middleware.js +6 -5
  10. package/dist/pages/login/page.js +28 -28
  11. package/dist/pages/settings/EnhancedSettingsPage.js +17 -17
  12. package/dist/vibe/sessions.js +28 -3
  13. package/package.json +2 -2
  14. package/scripts/check-publish-eol.mjs +33 -15
  15. package/src/api/auth-handler.ts +550 -550
  16. package/src/api/index.ts +17 -17
  17. package/src/api-handlers/account/change-password.ts +170 -170
  18. package/src/api-handlers/account/masked-info.ts +46 -46
  19. package/src/api-handlers/account/profile.ts +99 -99
  20. package/src/api-handlers/account/recovery/forward.ts +117 -117
  21. package/src/api-handlers/account/recovery/initiate.ts +59 -59
  22. package/src/api-handlers/account/recovery/send-code.ts +21 -21
  23. package/src/api-handlers/account/recovery/verify-code.ts +20 -20
  24. package/src/api-handlers/account/reset-password.ts +87 -87
  25. package/src/api-handlers/account/send-code.ts +70 -70
  26. package/src/api-handlers/account/update-phone.ts +84 -84
  27. package/src/api-handlers/account/validate-password.ts +139 -139
  28. package/src/api-handlers/account/verify-email.ts +134 -134
  29. package/src/api-handlers/account/verify-sms.ts +134 -134
  30. package/src/api-handlers/admin/analytics.ts +452 -452
  31. package/src/api-handlers/admin/audit.ts +232 -232
  32. package/src/api-handlers/admin/index.ts +63 -63
  33. package/src/api-handlers/admin/redis-sessions.ts +259 -259
  34. package/src/api-handlers/admin/sessions.ts +327 -327
  35. package/src/api-handlers/admin/site-logs.ts +388 -388
  36. package/src/api-handlers/admin/stats.ts +260 -260
  37. package/src/api-handlers/admin/users.ts +251 -251
  38. package/src/api-handlers/admin/vibe-data.ts +333 -333
  39. package/src/api-handlers/anon/preferences.ts +123 -123
  40. package/src/api-handlers/auth/credential-login-email-code.ts +92 -92
  41. package/src/api-handlers/auth/credential-login.ts +948 -948
  42. package/src/api-handlers/auth/jwks.ts +31 -31
  43. package/src/api-handlers/auth/login.ts +252 -252
  44. package/src/api-handlers/auth/passkey-signin.ts +116 -116
  45. package/src/api-handlers/auth/refresh.ts +829 -829
  46. package/src/api-handlers/auth/signout.ts +201 -201
  47. package/src/api-handlers/auth/status.ts +23 -23
  48. package/src/api-handlers/auth/update-session.ts +144 -144
  49. package/src/api-handlers/auth/validate.ts +45 -45
  50. package/src/api-handlers/auth/verify-code.ts +116 -116
  51. package/src/api-handlers/mfa/backup-code-verify.ts +170 -170
  52. package/src/api-handlers/mfa/backup-codes.ts +42 -42
  53. package/src/api-handlers/mfa/methods.ts +47 -47
  54. package/src/api-handlers/mfa/totp-confirm.ts +43 -43
  55. package/src/api-handlers/mfa/totp-enroll.ts +43 -43
  56. package/src/api-handlers/mfa/totp-verify.ts +172 -172
  57. package/src/api-handlers/oauth/resume.ts +182 -182
  58. package/src/api-handlers/onboarding/send-email-code.ts +18 -18
  59. package/src/api-handlers/onboarding/set-password.ts +21 -21
  60. package/src/api-handlers/onboarding/verify-code.ts +20 -20
  61. package/src/api-handlers/onboarding/verify-welcome-email.ts +17 -17
  62. package/src/api-handlers/passkeys/list.ts +32 -32
  63. package/src/api-handlers/passkeys/manage.ts +55 -55
  64. package/src/api-handlers/passkeys/register-options.ts +43 -43
  65. package/src/api-handlers/passkeys/register-verify.ts +42 -42
  66. package/src/api-handlers/session/refresh-viability.ts +56 -56
  67. package/src/api-handlers/session/viability.ts +238 -238
  68. package/src/api-handlers/test/force-expire.ts +167 -167
  69. package/src/auth/auth-decision.ts +292 -292
  70. package/src/auth/better-auth.ts +1688 -1688
  71. package/src/auth/idp-oauth.ts +310 -310
  72. package/src/auth/password-reset-bridge.ts +98 -98
  73. package/src/auth/route-config.ts +236 -236
  74. package/src/auth/safe-callback.ts +199 -199
  75. package/src/auth/session-cookie-clear.ts +30 -30
  76. package/src/auth/session-reset-link.ts +159 -159
  77. package/src/auth/session-response-sanitizer.ts +151 -151
  78. package/src/auth/types/auth-types.ts +555 -555
  79. package/src/auth/types/index.ts +7 -7
  80. package/src/auth/unauthenticated-routes.ts +2 -2
  81. package/src/auth/utils/idp-client.ts +364 -364
  82. package/src/auth/utils/index.ts +6 -6
  83. package/src/auth/utils/token-utils.ts +243 -243
  84. package/src/client/AuthContext.tsx +192 -192
  85. package/src/client/better-auth-client.ts +70 -70
  86. package/src/client/fetch-with-auth.ts +47 -47
  87. package/src/client/fetchWithSession.ts +21 -21
  88. package/src/client/index.ts +13 -13
  89. package/src/client/useAnonSession.ts +131 -131
  90. package/src/components/SessionSync.tsx +138 -138
  91. package/src/components/SignalRHealthCheck.tsx +131 -131
  92. package/src/components/account/MobileNavDrawer.tsx +305 -305
  93. package/src/components/account/UserAvatarMenu.tsx +277 -277
  94. package/src/components/account/index.ts +13 -13
  95. package/src/components/admin/AlertSettingsTab.tsx +728 -728
  96. package/src/components/admin/AnalyticsTab.tsx +703 -703
  97. package/src/components/admin/DataBrowserTab.tsx +508 -508
  98. package/src/components/admin/LoggingSettingsTab.tsx +665 -665
  99. package/src/components/admin/SessionsTab.tsx +421 -421
  100. package/src/components/admin/StatsTab.tsx +379 -379
  101. package/src/components/admin/VibeAdminContext.tsx +87 -87
  102. package/src/components/admin/VibeAdminLayout.tsx +187 -187
  103. package/src/components/admin/index.ts +59 -59
  104. package/src/components/auth/CredentialSignInForm.tsx +240 -240
  105. package/src/components/auth/FederatedAuthSection.tsx +129 -129
  106. package/src/components/auth/ModeAwareLoginPage.tsx +146 -146
  107. package/src/components/auth/ModeAwareSignupPage.tsx +200 -200
  108. package/src/components/auth/PasswordResetBridge.tsx +30 -30
  109. package/src/components/auth/TraditionalAuthSection.tsx +103 -103
  110. package/src/components/recovery/CompleteStep.tsx +36 -36
  111. package/src/components/recovery/InitiateRecoveryStep.tsx +68 -68
  112. package/src/components/recovery/RequestedStep.tsx +30 -30
  113. package/src/components/recovery/SelectMethodStep.tsx +73 -73
  114. package/src/components/recovery/SetPasswordStep.tsx +118 -118
  115. package/src/components/recovery/VerifyCodeStep.tsx +90 -90
  116. package/src/components/reserved/ReservedRecoveryWarning.tsx +160 -160
  117. package/src/components/reserved/ReservedStatusBox.tsx +118 -118
  118. package/src/components/ui/BetaBadge.tsx +58 -58
  119. package/src/components/ui/Footer.tsx +93 -93
  120. package/src/config/env.ts +55 -55
  121. package/src/config/logger.ts +62 -62
  122. package/src/config/logging-config.ts +82 -82
  123. package/src/config/unauthenticated-routes.ts +19 -19
  124. package/src/config/vibe-log-transport.ts +264 -264
  125. package/src/edge/internal-api-url.ts +65 -65
  126. package/src/edge/middleware.ts +42 -42
  127. package/src/hooks/useAuth.ts +117 -117
  128. package/src/hooks/useAuthSettings.ts +109 -109
  129. package/src/hooks/useAvailableProviders.ts +143 -143
  130. package/src/hooks/usePasswordValidation.ts +127 -127
  131. package/src/hooks/useProfile.ts +82 -82
  132. package/src/hooks/usePublicAuthSettings.ts +171 -171
  133. package/src/hooks/useSessionExpiration.ts +101 -101
  134. package/src/hooks/useViabilitySession.ts +337 -337
  135. package/src/index.ts +64 -64
  136. package/src/lib/anon-session.ts +213 -213
  137. package/src/lib/api-handler.ts +643 -643
  138. package/src/lib/app-slug.ts +228 -228
  139. package/src/lib/authorize-resume.ts +172 -172
  140. package/src/lib/bearer-fetch.ts +31 -31
  141. package/src/lib/client-key.ts +88 -88
  142. package/src/lib/code-step-copy.ts +83 -83
  143. package/src/lib/credential-sign-in-client.ts +101 -101
  144. package/src/lib/demo-mode.ts +18 -18
  145. package/src/lib/device-id.ts +67 -67
  146. package/src/lib/ensure-fresh-access-token.ts +509 -509
  147. package/src/lib/geolocation.ts +265 -265
  148. package/src/lib/idp-client-config.ts +1005 -1005
  149. package/src/lib/idp-fetch.ts +169 -169
  150. package/src/lib/idp-url-guard.ts +37 -37
  151. package/src/lib/internal-api.ts +171 -171
  152. package/src/lib/jwt-decode-client.ts +45 -45
  153. package/src/lib/jwt-decode.ts +82 -82
  154. package/src/lib/lock-window.ts +49 -49
  155. package/src/lib/login-error-message.ts +41 -41
  156. package/src/lib/never-in-response.ts +64 -64
  157. package/src/lib/nextauth-secret.ts +168 -168
  158. package/src/lib/onboarding-proxy.ts +57 -57
  159. package/src/lib/password-rules.ts +50 -50
  160. package/src/lib/rate-limit-service.ts +9 -9
  161. package/src/lib/redis.ts +105 -105
  162. package/src/lib/refresh-token-validator.ts +64 -64
  163. package/src/lib/roles.ts +177 -177
  164. package/src/lib/safe-error-response.ts +149 -149
  165. package/src/lib/secret-validation.ts +8 -8
  166. package/src/lib/session-cookie-shape.ts +185 -185
  167. package/src/lib/session-store.ts +1092 -1092
  168. package/src/lib/session.ts +34 -34
  169. package/src/lib/single-flight.ts +64 -64
  170. package/src/lib/site-logger.ts +245 -245
  171. package/src/lib/standardized-client-api.ts +901 -901
  172. package/src/lib/startup-init.ts +276 -276
  173. package/src/lib/test-aware-get-token.ts +41 -41
  174. package/src/lib/token-expiry.ts +40 -40
  175. package/src/lib/token-lifecycle.ts +546 -546
  176. package/src/lib/token-log-id.ts +69 -69
  177. package/src/lib/twofa-rejection.ts +91 -91
  178. package/src/lib/types/api-responses.ts +336 -336
  179. package/src/lib/user-agent-parser.ts +252 -252
  180. package/src/logging/api/admin-analytics.ts +51 -51
  181. package/src/logging/api/audit-log.ts +53 -53
  182. package/src/logging/components/AdminAnalyticsLayout.tsx +49 -49
  183. package/src/logging/components/AuditLogViewer.tsx +125 -125
  184. package/src/logging/components/ErrorMetricsCard.tsx +98 -98
  185. package/src/logging/components/HealthMetricsCard.tsx +70 -70
  186. package/src/logging/hooks/useAdminAnalytics.ts +22 -22
  187. package/src/logging/hooks/useAuditLog.ts +24 -24
  188. package/src/logging/hooks/useErrorMetrics.ts +40 -40
  189. package/src/logging/hooks/useHealthMetrics.ts +44 -44
  190. package/src/logging/index.ts +18 -18
  191. package/src/logging/types/analytics.ts +81 -81
  192. package/src/logging/types/audit.ts +31 -31
  193. package/src/logging/types/index.ts +3 -3
  194. package/src/middleware/create-middleware.ts +1139 -1138
  195. package/src/middleware/rbac-check.ts +279 -279
  196. package/src/middleware/twofa-presets.ts +224 -224
  197. package/src/models/DecodedAccessToken.ts +16 -16
  198. package/src/models/SessionModel.ts +331 -331
  199. package/src/pages/admin-login/page.tsx +111 -111
  200. package/src/pages/admin-page-permissions/PagePermissionsAdminPage.tsx +527 -527
  201. package/src/pages/admin-page-permissions/index.ts +7 -7
  202. package/src/pages/admin-roles/RolesAdminPage.tsx +533 -533
  203. package/src/pages/admin-roles/index.ts +9 -9
  204. package/src/pages/admin-roles/modals.tsx +469 -469
  205. package/src/pages/client-admin/ClientSiteAdminPage.tsx +382 -382
  206. package/src/pages/client-admin/index.ts +33 -33
  207. package/src/pages/coming-soon/page.tsx +83 -83
  208. package/src/pages/login/page.tsx +338 -338
  209. package/src/pages/onboarding/index.ts +11 -11
  210. package/src/pages/onboarding/page.tsx +212 -212
  211. package/src/pages/profile/EnhancedProfilePage.tsx +514 -514
  212. package/src/pages/profile/index.ts +9 -9
  213. package/src/pages/profile/page.tsx +166 -166
  214. package/src/pages/recovery/page.tsx +267 -267
  215. package/src/pages/roles/MyRolesPage.tsx +211 -211
  216. package/src/pages/roles/components.tsx +294 -294
  217. package/src/pages/roles/index.ts +17 -17
  218. package/src/pages/security/EnhancedSecurityPage.tsx +660 -660
  219. package/src/pages/security/index.ts +12 -12
  220. package/src/pages/security/page.tsx +507 -507
  221. package/src/pages/settings/EnhancedSettingsPage.tsx +642 -642
  222. package/src/pages/settings/index.ts +9 -9
  223. package/src/pages/settings/page.tsx +47 -47
  224. package/src/pages/showcase/ShowcasePage.tsx +532 -532
  225. package/src/pages/showcase/index.ts +13 -13
  226. package/src/pages/test-env/EmergencyLogoutPage.tsx +192 -192
  227. package/src/pages/test-env/JwtInspectPage.tsx +449 -449
  228. package/src/pages/test-env/RefreshTokenPage.tsx +178 -178
  229. package/src/pages/test-env/TestEnvPage.tsx +130 -130
  230. package/src/pages/test-env/guarded.tsx +81 -81
  231. package/src/pages/test-env/index.ts +77 -77
  232. package/src/pages/test-env/redact-credentials.ts +96 -96
  233. package/src/pages/verify-code/page.tsx +746 -746
  234. package/src/routes/account/index.ts +31 -31
  235. package/src/routes/account/masked-info.ts +36 -36
  236. package/src/routes/account/send-code.ts +39 -39
  237. package/src/routes/account/update-phone.ts +13 -13
  238. package/src/routes/account/verify-email.ts +40 -40
  239. package/src/routes/account/verify-sms.ts +40 -40
  240. package/src/routes/auth/credential-login-email-code.ts +6 -6
  241. package/src/routes/auth/credential-login.ts +6 -6
  242. package/src/routes/auth/index.ts +22 -22
  243. package/src/routes/auth/logout.ts +111 -111
  244. package/src/routes/auth/nextauth.ts +45 -45
  245. package/src/routes/auth/passkey-signin.ts +13 -13
  246. package/src/routes/auth/refresh.ts +77 -77
  247. package/src/routes/auth/session-reset.ts +37 -37
  248. package/src/routes/auth/session.ts +261 -261
  249. package/src/routes/auth/settings.ts +181 -181
  250. package/src/routes/auth/viability.ts +519 -519
  251. package/src/routes/index.ts +17 -17
  252. package/src/routes/mfa/backup-code-verify.ts +1 -1
  253. package/src/routes/mfa/backup-codes.ts +10 -10
  254. package/src/routes/mfa/methods.ts +22 -22
  255. package/src/routes/mfa/totp-confirm.ts +10 -10
  256. package/src/routes/mfa/totp-enroll.ts +10 -10
  257. package/src/routes/mfa/totp-verify.ts +14 -14
  258. package/src/routes/onboarding/index.ts +15 -15
  259. package/src/routes/onboarding/send-email-code.ts +2 -2
  260. package/src/routes/onboarding/set-password.ts +2 -2
  261. package/src/routes/onboarding/verify-code.ts +2 -2
  262. package/src/routes/onboarding/verify-welcome-email.ts +2 -2
  263. package/src/routes/passkeys/list.ts +10 -10
  264. package/src/routes/passkeys/manage.ts +23 -23
  265. package/src/routes/passkeys/register-options.ts +10 -10
  266. package/src/routes/passkeys/register-verify.ts +10 -10
  267. package/src/routes/session/index.ts +7 -7
  268. package/src/routes/session/refresh-viability.ts +17 -17
  269. package/src/server/auth-guard.ts +203 -203
  270. package/src/server/auth.ts +486 -486
  271. package/src/server/decode-session.ts +309 -309
  272. package/src/server/slim-middleware.ts +117 -117
  273. package/src/server/verified-session-token.ts +103 -103
  274. package/src/server/with-auth.ts +93 -93
  275. package/src/services/signalrActivityService.ts +258 -258
  276. package/src/stores/authStore.ts +1900 -1900
  277. package/src/templates/instrumentation.ts +60 -60
  278. package/src/theme/ThemeProvider.tsx +39 -39
  279. package/src/theme/default.ts +33 -33
  280. package/src/theme/index.ts +31 -31
  281. package/src/theme/types.ts +69 -69
  282. package/src/theme/useTheme.ts +57 -57
  283. package/src/theme/utils.ts +40 -40
  284. package/src/types/api.ts +12 -12
  285. package/src/types/auth.d.ts +23 -23
  286. package/src/types/auth.ts +48 -48
  287. package/src/types/logging.ts +11 -11
  288. package/src/types/recovery.ts +54 -54
  289. package/src/utils/api.ts +401 -401
  290. package/src/utils/circuitBreaker.ts +40 -40
  291. package/src/utils/error-message.ts +108 -108
  292. package/src/utils/layout/reservedSpace.ts +124 -124
  293. package/src/utils/logout.ts +30 -30
  294. package/src/vibe/client.ts +877 -877
  295. package/src/vibe/enterprise-auth.ts +208 -208
  296. package/src/vibe/errors.ts +209 -209
  297. package/src/vibe/generic.ts +339 -339
  298. package/src/vibe/hooks/index.ts +367 -367
  299. package/src/vibe/index.ts +133 -133
  300. package/src/vibe/sessions.ts +925 -899
  301. package/src/vibe/types.ts +577 -577
@@ -1,331 +1,331 @@
1
- /**
2
- * Session Model - Redis Session Data Structure
3
- *
4
- * This is the single source of truth for session data stored in Redis.
5
- * The session contains all authentication state - the JWT cookie only
6
- * stores the session ID (redisSessionId).
7
- *
8
- * FIELD NAMING CONVENTIONS:
9
- * - idp* prefix: Tokens from PayEz IDP (identity provider)
10
- * - oauth* prefix: Tokens from external OAuth providers (Google, etc.)
11
- * - mfa* prefix: Multi-factor authentication related fields
12
- *
13
- * @version 2.0.0 - Normalized field names
14
- * @since auth-refactor-2026-01
15
- */
16
-
17
- // ============================================================================
18
- // NORMALIZED SESSION DATA (v2)
19
- // ============================================================================
20
-
21
- /**
22
- * Session data stored in Redis.
23
- *
24
- * This interface uses normalized field names for clarity.
25
- * All tokens and user data live here - the browser only gets the session ID.
26
- */
27
- export interface SessionData {
28
- // -------------------------------------------------------------------------
29
- // Core Identity
30
- // -------------------------------------------------------------------------
31
-
32
- /** User ID from IDP (sub claim) */
33
- userId: string;
34
-
35
- /** User's email address */
36
- email: string;
37
-
38
- /** Display name (from OAuth profile or IDP) */
39
- name?: string;
40
-
41
- /** Avatar image URL (from OAuth profile) */
42
- image?: string;
43
-
44
- /** User's roles/permissions */
45
- roles: string[];
46
-
47
- // -------------------------------------------------------------------------
48
- // IDP Tokens (from PayEz Identity Provider)
49
- // -------------------------------------------------------------------------
50
-
51
- /** IDP access token (JWT) - used for API calls to PayEz services */
52
- idpAccessToken?: string;
53
-
54
- /** IDP refresh token - used to get new access tokens */
55
- idpRefreshToken?: string;
56
-
57
- /** When the IDP access token expires (Unix timestamp ms) */
58
- idpAccessTokenExpires: number;
59
-
60
- /** When the IDP refresh token expires (Unix timestamp ms) */
61
- idpRefreshTokenExpires?: number;
62
-
63
- /** Decoded IDP access token claims (for quick access without re-decoding) */
64
- decodedAccessToken?: any;
65
-
66
- /**
67
- * Bearer Key ID (kid from JWT header).
68
- * Identifies which IDP signing key was used for this token.
69
- * CRITICAL: This is from the JWT HEADER, not client_id from payload.
70
- */
71
- bearerKeyId?: string;
72
-
73
- // -------------------------------------------------------------------------
74
- // MFA (Multi-Factor Authentication) State
75
- // -------------------------------------------------------------------------
76
-
77
- /** Whether MFA has been verified for this session */
78
- mfaVerified: boolean;
79
-
80
- /**
81
- * *** R807 (BAPert, card 362550). DID THE PRODUCER ACTUALLY SAY ANYTHING ABOUT MFA? ***
82
- *
83
- * `mfaVerified` above is deliberately FAIL-CLOSED: every construction site
84
- * collapses an absent value to `false` (`?? false`), so by the time anyone
85
- * reads it, "the producer said false" and "the producer said nothing" are
86
- * indistinguishable. That collapse is CORRECT and must not be removed - a
87
- * security consumer treating absence as "verified" is an AUTH BYPASS.
88
- *
89
- * But `routes/auth/viability.ts` asks a genuinely different question: "did the
90
- * OAuth callback AFFIRMATIVELY set false, or did we simply never know?" It
91
- * cannot ask that of a field whose absence has already been collapsed. This
92
- * field carries that one bit, so the collapse can stay.
93
- *
94
- * true -> the producer emitted an explicit mfaVerified; `mfaVerified` is a measurement.
95
- * false -> the producer emitted nothing; `mfaVerified`'s `false` is a DEFAULT, not a signal.
96
- * undefined -> LEGACY SESSION, minted before this field existed. Same meaning as `false`
97
- * for viability (do NOT force a re-challenge), and it is why this is
98
- * optional rather than defaulted: `?? false` here would be the very
99
- * absence-destroying move this field exists to undo.
100
- *
101
- * *** CONFINED, BY RULING: THIS FIELD MUST NEVER REACH AN AUTH DECISION. ***
102
- * It exists to make viability LESS aggressive (suppressing a mass re-challenge of
103
- * the pre-existing session population). Letting it influence an auth path would
104
- * turn a permissive read into a fail-open, and R807 is void if it does. Gate on
105
- * `mfaVerified` for anything that grants access; gate on this only to decide
106
- * whether `mfaVerified === false` was a real statement.
107
- *
108
- * *** DECLARING IT HERE IS LOAD-BEARING FOR MORE THAN DOCUMENTATION. ***
109
- * `SessionData` carries `[key: string]: any` (the "backward compatibility"
110
- * member at the END of this interface, added for migration back-compat — it
111
- * was line 147 before this block was inserted above it, which is the number
112
- * quoted in R807/362550; adding these lines moved it down, so find it by name,
113
- * not by number). Any field NOT declared explicitly is absorbed by that index
114
- * signature and becomes `any` - so an undeclared `mfaSignalPresent` would let a
115
- * typo at the consumer compile clean and read `undefined` forever, silently
116
- * disabling the viability override. Measured, not assumed: see the card.
117
- */
118
- mfaSignalPresent?: boolean;
119
-
120
- /**
121
- * The IDP's own routing decision for a 2FA-pending login (cards 141688 /
122
- * 141741, IDP WO 113023). Wire name is snake — `next_step`.
123
- *
124
- * 'enroll_mfa' — no USABLE method (confirmed and not revoked). The user
125
- * cannot complete a challenge; they must enrol first.
126
- * 'mfa_verify' — a usable method exists; challenge them.
127
- * null — fully authenticated, nothing outstanding.
128
- *
129
- * RELAYED, NEVER DERIVED. The IDP owns this fact and is already usable-aware;
130
- * recomputing it here from a method count would make a second owner and would
131
- * get the revoked-method case wrong (count>0 but usable=0).
132
- *
133
- * NOT A COMPLETION SIGNAL. 'mfa_verify' means "can be challenged", not
134
- * "is through". `mfaVerified` remains the only field that says they verified.
135
- */
136
- nextStep?: 'enroll_mfa' | 'mfa_verify' | null;
137
-
138
- /** The MFA method used (email, sms, totp) */
139
- mfaMethod?: 'email' | 'sms' | 'totp';
140
-
141
- /** When MFA was completed (Unix timestamp ms) */
142
- mfaCompletedAt?: number;
143
-
144
- /** When MFA verification expires (Unix timestamp ms) */
145
- mfaExpiresAt?: number;
146
-
147
- /** How long MFA is valid in hours */
148
- mfaValidityHours?: number;
149
-
150
- /** Authentication methods from token (amr claim) */
151
- authenticationMethods?: string[];
152
-
153
- /** Authentication level from token (acr claim) */
154
- authenticationLevel?: string;
155
-
156
- // -------------------------------------------------------------------------
157
- // OAuth Provider Tokens (Google, Microsoft, etc.)
158
- // -------------------------------------------------------------------------
159
-
160
- /** Which OAuth provider was used (google, apple, microsoft, etc.) */
161
- oauthProvider?: string;
162
-
163
- /** Access token from OAuth provider */
164
- oauthProviderToken?: string;
165
-
166
- /** Refresh token from OAuth provider */
167
- oauthProviderRefreshToken?: string;
168
-
169
- // -------------------------------------------------------------------------
170
- // Multi-Tenant IDP Assignment
171
- // -------------------------------------------------------------------------
172
-
173
- /** IDP client ID this user belongs to */
174
- idpClientId?: string;
175
-
176
- /** Merchant ID (typically same as client ID) */
177
- merchantId?: string;
178
-
179
- // -------------------------------------------------------------------------
180
- // Legacy Field Support (for backward compatibility)
181
- // -------------------------------------------------------------------------
182
-
183
- /**
184
- * Allow any additional fields for backward compatibility.
185
- * During migration, old sessions may have legacy field names.
186
- */
187
- [key: string]: any;
188
- }
189
-
190
-
191
- // ============================================================================
192
- // SESSION MODEL CLASS
193
- // ============================================================================
194
-
195
- /**
196
- * Session model class for working with session data.
197
- *
198
- * Provides typed access to session fields with normalized names.
199
- */
200
- export class SessionModel {
201
- // Core Identity
202
- userId: string;
203
- email: string;
204
- name?: string;
205
- image?: string;
206
- roles: string[];
207
-
208
- // IDP Tokens
209
- idpAccessToken?: string;
210
- idpRefreshToken?: string;
211
- idpAccessTokenExpires: number;
212
- idpRefreshTokenExpires?: number;
213
- decodedAccessToken?: any;
214
- bearerKeyId?: string;
215
-
216
- // MFA State
217
- mfaVerified: boolean;
218
- /** R807: see SessionData.mfaSignalPresent. Propagated verbatim, never defaulted. */
219
- mfaSignalPresent?: boolean;
220
- mfaMethod?: 'email' | 'sms' | 'totp';
221
- mfaCompletedAt?: number;
222
- mfaExpiresAt?: number;
223
- mfaValidityHours?: number;
224
- authenticationMethods?: string[];
225
- authenticationLevel?: string;
226
-
227
- // OAuth Provider
228
- oauthProvider?: string;
229
- oauthProviderToken?: string;
230
- oauthProviderRefreshToken?: string;
231
-
232
- // Multi-Tenant
233
- idpClientId?: string;
234
- merchantId?: string;
235
-
236
- constructor(data: SessionData) {
237
- // Core Identity
238
- this.userId = data.userId;
239
- this.email = data.email;
240
- this.name = data.name;
241
- this.image = data.image;
242
- this.roles = data.roles || [];
243
-
244
- // IDP Tokens
245
- this.idpAccessToken = data.idpAccessToken;
246
- this.idpRefreshToken = data.idpRefreshToken;
247
- this.idpAccessTokenExpires = data.idpAccessTokenExpires;
248
- this.idpRefreshTokenExpires = data.idpRefreshTokenExpires;
249
- this.decodedAccessToken = data.decodedAccessToken;
250
- this.bearerKeyId = data.bearerKeyId;
251
-
252
- // MFA State
253
- this.mfaVerified = data.mfaVerified ?? false;
254
- // *** R807: PROPAGATE, DO NOT DEFAULT. *** `?? false` here would destroy the
255
- // legacy/never-knew distinction on every path through this class - invisibly,
256
- // because callers construct a SessionModel without restating the field.
257
- this.mfaSignalPresent = data.mfaSignalPresent;
258
- this.mfaMethod = data.mfaMethod;
259
- this.mfaCompletedAt = data.mfaCompletedAt;
260
- this.mfaExpiresAt = data.mfaExpiresAt;
261
- this.mfaValidityHours = data.mfaValidityHours;
262
- this.authenticationMethods = data.authenticationMethods;
263
- this.authenticationLevel = data.authenticationLevel;
264
-
265
- // OAuth Provider
266
- this.oauthProvider = data.oauthProvider;
267
- this.oauthProviderToken = data.oauthProviderToken;
268
- this.oauthProviderRefreshToken = data.oauthProviderRefreshToken;
269
-
270
- // Multi-Tenant
271
- this.idpClientId = data.idpClientId;
272
- this.merchantId = data.merchantId;
273
- }
274
-
275
- /**
276
- * Check if the IDP access token has expired.
277
- */
278
- isAccessTokenExpired(): boolean {
279
- return Date.now() >= this.idpAccessTokenExpires;
280
- }
281
-
282
- /**
283
- * Check if the IDP refresh token has expired.
284
- */
285
- isRefreshTokenExpired(): boolean {
286
- if (!this.idpRefreshTokenExpires) return false;
287
- return Date.now() >= this.idpRefreshTokenExpires;
288
- }
289
-
290
- /**
291
- * Check if MFA has expired.
292
- */
293
- isMfaExpired(): boolean {
294
- if (!this.mfaExpiresAt) return false;
295
- return Date.now() > this.mfaExpiresAt;
296
- }
297
-
298
- /**
299
- * Convert to plain object for storage.
300
- */
301
- toJSON(): SessionData {
302
- return {
303
- userId: this.userId,
304
- email: this.email,
305
- name: this.name,
306
- image: this.image,
307
- roles: this.roles,
308
- idpAccessToken: this.idpAccessToken,
309
- idpRefreshToken: this.idpRefreshToken,
310
- idpAccessTokenExpires: this.idpAccessTokenExpires,
311
- idpRefreshTokenExpires: this.idpRefreshTokenExpires,
312
- decodedAccessToken: this.decodedAccessToken,
313
- bearerKeyId: this.bearerKeyId,
314
- mfaVerified: this.mfaVerified,
315
- // R807: must survive the Redis round-trip, or the session is re-read as
316
- // `legacy` one hop later and viability silently stops firing.
317
- mfaSignalPresent: this.mfaSignalPresent,
318
- mfaMethod: this.mfaMethod,
319
- mfaCompletedAt: this.mfaCompletedAt,
320
- mfaExpiresAt: this.mfaExpiresAt,
321
- mfaValidityHours: this.mfaValidityHours,
322
- authenticationMethods: this.authenticationMethods,
323
- authenticationLevel: this.authenticationLevel,
324
- oauthProvider: this.oauthProvider,
325
- oauthProviderToken: this.oauthProviderToken,
326
- oauthProviderRefreshToken: this.oauthProviderRefreshToken,
327
- idpClientId: this.idpClientId,
328
- merchantId: this.merchantId,
329
- };
330
- }
331
- }
1
+ /**
2
+ * Session Model - Redis Session Data Structure
3
+ *
4
+ * This is the single source of truth for session data stored in Redis.
5
+ * The session contains all authentication state - the JWT cookie only
6
+ * stores the session ID (redisSessionId).
7
+ *
8
+ * FIELD NAMING CONVENTIONS:
9
+ * - idp* prefix: Tokens from PayEz IDP (identity provider)
10
+ * - oauth* prefix: Tokens from external OAuth providers (Google, etc.)
11
+ * - mfa* prefix: Multi-factor authentication related fields
12
+ *
13
+ * @version 2.0.0 - Normalized field names
14
+ * @since auth-refactor-2026-01
15
+ */
16
+
17
+ // ============================================================================
18
+ // NORMALIZED SESSION DATA (v2)
19
+ // ============================================================================
20
+
21
+ /**
22
+ * Session data stored in Redis.
23
+ *
24
+ * This interface uses normalized field names for clarity.
25
+ * All tokens and user data live here - the browser only gets the session ID.
26
+ */
27
+ export interface SessionData {
28
+ // -------------------------------------------------------------------------
29
+ // Core Identity
30
+ // -------------------------------------------------------------------------
31
+
32
+ /** User ID from IDP (sub claim) */
33
+ userId: string;
34
+
35
+ /** User's email address */
36
+ email: string;
37
+
38
+ /** Display name (from OAuth profile or IDP) */
39
+ name?: string;
40
+
41
+ /** Avatar image URL (from OAuth profile) */
42
+ image?: string;
43
+
44
+ /** User's roles/permissions */
45
+ roles: string[];
46
+
47
+ // -------------------------------------------------------------------------
48
+ // IDP Tokens (from PayEz Identity Provider)
49
+ // -------------------------------------------------------------------------
50
+
51
+ /** IDP access token (JWT) - used for API calls to PayEz services */
52
+ idpAccessToken?: string;
53
+
54
+ /** IDP refresh token - used to get new access tokens */
55
+ idpRefreshToken?: string;
56
+
57
+ /** When the IDP access token expires (Unix timestamp ms) */
58
+ idpAccessTokenExpires: number;
59
+
60
+ /** When the IDP refresh token expires (Unix timestamp ms) */
61
+ idpRefreshTokenExpires?: number;
62
+
63
+ /** Decoded IDP access token claims (for quick access without re-decoding) */
64
+ decodedAccessToken?: any;
65
+
66
+ /**
67
+ * Bearer Key ID (kid from JWT header).
68
+ * Identifies which IDP signing key was used for this token.
69
+ * CRITICAL: This is from the JWT HEADER, not client_id from payload.
70
+ */
71
+ bearerKeyId?: string;
72
+
73
+ // -------------------------------------------------------------------------
74
+ // MFA (Multi-Factor Authentication) State
75
+ // -------------------------------------------------------------------------
76
+
77
+ /** Whether MFA has been verified for this session */
78
+ mfaVerified: boolean;
79
+
80
+ /**
81
+ * *** R807 (BAPert, card 362550). DID THE PRODUCER ACTUALLY SAY ANYTHING ABOUT MFA? ***
82
+ *
83
+ * `mfaVerified` above is deliberately FAIL-CLOSED: every construction site
84
+ * collapses an absent value to `false` (`?? false`), so by the time anyone
85
+ * reads it, "the producer said false" and "the producer said nothing" are
86
+ * indistinguishable. That collapse is CORRECT and must not be removed - a
87
+ * security consumer treating absence as "verified" is an AUTH BYPASS.
88
+ *
89
+ * But `routes/auth/viability.ts` asks a genuinely different question: "did the
90
+ * OAuth callback AFFIRMATIVELY set false, or did we simply never know?" It
91
+ * cannot ask that of a field whose absence has already been collapsed. This
92
+ * field carries that one bit, so the collapse can stay.
93
+ *
94
+ * true -> the producer emitted an explicit mfaVerified; `mfaVerified` is a measurement.
95
+ * false -> the producer emitted nothing; `mfaVerified`'s `false` is a DEFAULT, not a signal.
96
+ * undefined -> LEGACY SESSION, minted before this field existed. Same meaning as `false`
97
+ * for viability (do NOT force a re-challenge), and it is why this is
98
+ * optional rather than defaulted: `?? false` here would be the very
99
+ * absence-destroying move this field exists to undo.
100
+ *
101
+ * *** CONFINED, BY RULING: THIS FIELD MUST NEVER REACH AN AUTH DECISION. ***
102
+ * It exists to make viability LESS aggressive (suppressing a mass re-challenge of
103
+ * the pre-existing session population). Letting it influence an auth path would
104
+ * turn a permissive read into a fail-open, and R807 is void if it does. Gate on
105
+ * `mfaVerified` for anything that grants access; gate on this only to decide
106
+ * whether `mfaVerified === false` was a real statement.
107
+ *
108
+ * *** DECLARING IT HERE IS LOAD-BEARING FOR MORE THAN DOCUMENTATION. ***
109
+ * `SessionData` carries `[key: string]: any` (the "backward compatibility"
110
+ * member at the END of this interface, added for migration back-compat — it
111
+ * was line 147 before this block was inserted above it, which is the number
112
+ * quoted in R807/362550; adding these lines moved it down, so find it by name,
113
+ * not by number). Any field NOT declared explicitly is absorbed by that index
114
+ * signature and becomes `any` - so an undeclared `mfaSignalPresent` would let a
115
+ * typo at the consumer compile clean and read `undefined` forever, silently
116
+ * disabling the viability override. Measured, not assumed: see the card.
117
+ */
118
+ mfaSignalPresent?: boolean;
119
+
120
+ /**
121
+ * The IDP's own routing decision for a 2FA-pending login (cards 141688 /
122
+ * 141741, IDP WO 113023). Wire name is snake — `next_step`.
123
+ *
124
+ * 'enroll_mfa' — no USABLE method (confirmed and not revoked). The user
125
+ * cannot complete a challenge; they must enrol first.
126
+ * 'mfa_verify' — a usable method exists; challenge them.
127
+ * null — fully authenticated, nothing outstanding.
128
+ *
129
+ * RELAYED, NEVER DERIVED. The IDP owns this fact and is already usable-aware;
130
+ * recomputing it here from a method count would make a second owner and would
131
+ * get the revoked-method case wrong (count>0 but usable=0).
132
+ *
133
+ * NOT A COMPLETION SIGNAL. 'mfa_verify' means "can be challenged", not
134
+ * "is through". `mfaVerified` remains the only field that says they verified.
135
+ */
136
+ nextStep?: 'enroll_mfa' | 'mfa_verify' | null;
137
+
138
+ /** The MFA method used (email, sms, totp) */
139
+ mfaMethod?: 'email' | 'sms' | 'totp';
140
+
141
+ /** When MFA was completed (Unix timestamp ms) */
142
+ mfaCompletedAt?: number;
143
+
144
+ /** When MFA verification expires (Unix timestamp ms) */
145
+ mfaExpiresAt?: number;
146
+
147
+ /** How long MFA is valid in hours */
148
+ mfaValidityHours?: number;
149
+
150
+ /** Authentication methods from token (amr claim) */
151
+ authenticationMethods?: string[];
152
+
153
+ /** Authentication level from token (acr claim) */
154
+ authenticationLevel?: string;
155
+
156
+ // -------------------------------------------------------------------------
157
+ // OAuth Provider Tokens (Google, Microsoft, etc.)
158
+ // -------------------------------------------------------------------------
159
+
160
+ /** Which OAuth provider was used (google, apple, microsoft, etc.) */
161
+ oauthProvider?: string;
162
+
163
+ /** Access token from OAuth provider */
164
+ oauthProviderToken?: string;
165
+
166
+ /** Refresh token from OAuth provider */
167
+ oauthProviderRefreshToken?: string;
168
+
169
+ // -------------------------------------------------------------------------
170
+ // Multi-Tenant IDP Assignment
171
+ // -------------------------------------------------------------------------
172
+
173
+ /** IDP client ID this user belongs to */
174
+ idpClientId?: string;
175
+
176
+ /** Merchant ID (typically same as client ID) */
177
+ merchantId?: string;
178
+
179
+ // -------------------------------------------------------------------------
180
+ // Legacy Field Support (for backward compatibility)
181
+ // -------------------------------------------------------------------------
182
+
183
+ /**
184
+ * Allow any additional fields for backward compatibility.
185
+ * During migration, old sessions may have legacy field names.
186
+ */
187
+ [key: string]: any;
188
+ }
189
+
190
+
191
+ // ============================================================================
192
+ // SESSION MODEL CLASS
193
+ // ============================================================================
194
+
195
+ /**
196
+ * Session model class for working with session data.
197
+ *
198
+ * Provides typed access to session fields with normalized names.
199
+ */
200
+ export class SessionModel {
201
+ // Core Identity
202
+ userId: string;
203
+ email: string;
204
+ name?: string;
205
+ image?: string;
206
+ roles: string[];
207
+
208
+ // IDP Tokens
209
+ idpAccessToken?: string;
210
+ idpRefreshToken?: string;
211
+ idpAccessTokenExpires: number;
212
+ idpRefreshTokenExpires?: number;
213
+ decodedAccessToken?: any;
214
+ bearerKeyId?: string;
215
+
216
+ // MFA State
217
+ mfaVerified: boolean;
218
+ /** R807: see SessionData.mfaSignalPresent. Propagated verbatim, never defaulted. */
219
+ mfaSignalPresent?: boolean;
220
+ mfaMethod?: 'email' | 'sms' | 'totp';
221
+ mfaCompletedAt?: number;
222
+ mfaExpiresAt?: number;
223
+ mfaValidityHours?: number;
224
+ authenticationMethods?: string[];
225
+ authenticationLevel?: string;
226
+
227
+ // OAuth Provider
228
+ oauthProvider?: string;
229
+ oauthProviderToken?: string;
230
+ oauthProviderRefreshToken?: string;
231
+
232
+ // Multi-Tenant
233
+ idpClientId?: string;
234
+ merchantId?: string;
235
+
236
+ constructor(data: SessionData) {
237
+ // Core Identity
238
+ this.userId = data.userId;
239
+ this.email = data.email;
240
+ this.name = data.name;
241
+ this.image = data.image;
242
+ this.roles = data.roles || [];
243
+
244
+ // IDP Tokens
245
+ this.idpAccessToken = data.idpAccessToken;
246
+ this.idpRefreshToken = data.idpRefreshToken;
247
+ this.idpAccessTokenExpires = data.idpAccessTokenExpires;
248
+ this.idpRefreshTokenExpires = data.idpRefreshTokenExpires;
249
+ this.decodedAccessToken = data.decodedAccessToken;
250
+ this.bearerKeyId = data.bearerKeyId;
251
+
252
+ // MFA State
253
+ this.mfaVerified = data.mfaVerified ?? false;
254
+ // *** R807: PROPAGATE, DO NOT DEFAULT. *** `?? false` here would destroy the
255
+ // legacy/never-knew distinction on every path through this class - invisibly,
256
+ // because callers construct a SessionModel without restating the field.
257
+ this.mfaSignalPresent = data.mfaSignalPresent;
258
+ this.mfaMethod = data.mfaMethod;
259
+ this.mfaCompletedAt = data.mfaCompletedAt;
260
+ this.mfaExpiresAt = data.mfaExpiresAt;
261
+ this.mfaValidityHours = data.mfaValidityHours;
262
+ this.authenticationMethods = data.authenticationMethods;
263
+ this.authenticationLevel = data.authenticationLevel;
264
+
265
+ // OAuth Provider
266
+ this.oauthProvider = data.oauthProvider;
267
+ this.oauthProviderToken = data.oauthProviderToken;
268
+ this.oauthProviderRefreshToken = data.oauthProviderRefreshToken;
269
+
270
+ // Multi-Tenant
271
+ this.idpClientId = data.idpClientId;
272
+ this.merchantId = data.merchantId;
273
+ }
274
+
275
+ /**
276
+ * Check if the IDP access token has expired.
277
+ */
278
+ isAccessTokenExpired(): boolean {
279
+ return Date.now() >= this.idpAccessTokenExpires;
280
+ }
281
+
282
+ /**
283
+ * Check if the IDP refresh token has expired.
284
+ */
285
+ isRefreshTokenExpired(): boolean {
286
+ if (!this.idpRefreshTokenExpires) return false;
287
+ return Date.now() >= this.idpRefreshTokenExpires;
288
+ }
289
+
290
+ /**
291
+ * Check if MFA has expired.
292
+ */
293
+ isMfaExpired(): boolean {
294
+ if (!this.mfaExpiresAt) return false;
295
+ return Date.now() > this.mfaExpiresAt;
296
+ }
297
+
298
+ /**
299
+ * Convert to plain object for storage.
300
+ */
301
+ toJSON(): SessionData {
302
+ return {
303
+ userId: this.userId,
304
+ email: this.email,
305
+ name: this.name,
306
+ image: this.image,
307
+ roles: this.roles,
308
+ idpAccessToken: this.idpAccessToken,
309
+ idpRefreshToken: this.idpRefreshToken,
310
+ idpAccessTokenExpires: this.idpAccessTokenExpires,
311
+ idpRefreshTokenExpires: this.idpRefreshTokenExpires,
312
+ decodedAccessToken: this.decodedAccessToken,
313
+ bearerKeyId: this.bearerKeyId,
314
+ mfaVerified: this.mfaVerified,
315
+ // R807: must survive the Redis round-trip, or the session is re-read as
316
+ // `legacy` one hop later and viability silently stops firing.
317
+ mfaSignalPresent: this.mfaSignalPresent,
318
+ mfaMethod: this.mfaMethod,
319
+ mfaCompletedAt: this.mfaCompletedAt,
320
+ mfaExpiresAt: this.mfaExpiresAt,
321
+ mfaValidityHours: this.mfaValidityHours,
322
+ authenticationMethods: this.authenticationMethods,
323
+ authenticationLevel: this.authenticationLevel,
324
+ oauthProvider: this.oauthProvider,
325
+ oauthProviderToken: this.oauthProviderToken,
326
+ oauthProviderRefreshToken: this.oauthProviderRefreshToken,
327
+ idpClientId: this.idpClientId,
328
+ merchantId: this.merchantId,
329
+ };
330
+ }
331
+ }