@payez/next-mvp 4.1.10 → 4.1.20

package/src/pages/login/page.tsx

@@ -30,10 +30,13 @@ import ReservedStatusBox from '../../components/reserved/ReservedStatusBox';
 import ReservedRecoveryWarning from '../../components/reserved/ReservedRecoveryWarning';
 import { useBranding, useColors, useLayout } from '../../theme/useTheme';
 
-function LoginForm() {
+function LoginForm({ altAuthSlot }: { altAuthSlot?: React.ReactNode }) {
   const searchParams = useSearchParams();
   const callbackUrl = searchParams?.get('callbackUrl') || '/dashboard';
   const urlError = searchParams?.get('error');
+  // Better Auth mount redirects OAuth failures here as ?oauth_error={provider}
+  // (the failure-signal guard from the merge spec). Distinct from `error`.
+  const oauthError = searchParams?.get('oauth_error');
 
   const { data: sessionData, isPending } = authClient.useSession();
   const session = sessionData;
@@ -42,6 +45,53 @@ function LoginForm() {
   const colors = useColors();
   const layout = useLayout();
 
+  // Social sign-in. The button renders ONLY when the IDP client config has an
+  // enabled provider row — discovered from the public settings route (the same
+  // config the Better Auth engine builds providers from), never assumed.
+  // Absent row / fetch failure = no button. Fail quiet is correct here.
+  const [googleEnabled, setGoogleEnabled] = useState(false);
+  const [googleLoading, setGoogleLoading] = useState(false);
+
+  useEffect(() => {
+    let mounted = true;
+    fetch('/api/auth/settings', { cache: 'no-store' })
+      .then((r) => (r.ok ? r.json() : null))
+      .then((json) => {
+        if (!mounted || !json) return;
+        const providers: unknown = json?.data?.enabledProviders;
+        if (Array.isArray(providers) && providers.some((p) => typeof p === 'string' && p.toLowerCase() === 'google')) {
+          setGoogleEnabled(true);
+        }
+      })
+      .catch(() => undefined); // fail quiet: no button
+    return () => { mounted = false; };
+  }, []);
+
+  const handleGoogleSignIn = async () => {
+    setGoogleLoading(true);
+    setLoginError(null);
+    try {
+      // Pre-clean any stale session so account-switch works (idealvibe
+      // account-auth/login idiom: signOut before signIn.social).
+      await authClient.signOut().catch(() => undefined);
+      // The package's OWN SDK, not a raw fetch — Jon's ruling (QA 17400 /
+      // BAPert 17401): the page is the template consumers copy, so it teaches
+      // the same one-line idiom idealvibe uses (49cc95f, four call sites).
+      // The SDK hits POST /api/auth/sign-in/social itself, with its own
+      // credentials mode, baseURL and error contract, and navigates on the
+      // returned authorize URL.
+      await authClient.signIn.social({
+        provider: 'google',
+        // The social round trip lands on '/', not the form's /dashboard
+        // default: the post-callback session upgrade decides the destination.
+        callbackURL: searchParams?.get('callbackUrl') || '/',
+      });
+    } catch {
+      setGoogleLoading(false);
+      setLoginError('Google sign-in is unavailable right now. Please try again.');
+    }
+  };
+
   // Helper to create lighter/darker shades for hover states
   const adjustBrightness = (hex: string, percent: number) => {
     const num = parseInt(hex.replace('#', ''), 16);
@@ -74,6 +124,14 @@ function LoginForm() {
   // Force show form after timeout if stuck in loading
   const [forceShowForm, setForceShowForm] = useState(false);
 
+  // Surface OAuth failures the Better Auth mount bounced back here.
+  useEffect(() => {
+    if (oauthError) {
+      const name = oauthError.charAt(0).toUpperCase() + oauthError.slice(1);
+      setLoginError(`${name} sign-in did not complete. Please try again.`);
+    }
+  }, [oauthError]);
+
   // Handle URL errors with user-friendly messages
   useEffect(() => {
     if (urlError) {
@@ -119,71 +177,9 @@ function LoginForm() {
     return () => clearTimeout(immediateTimeout);
   }, [status, session]);
 
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-
-    // Atomic state: set to submitting (clears error and success)
-    setIsSubmitting(true);
-    setLoading(true);
-    setLoginError(null);
-    setLoginSuccess(false);
-
-    try {
-      console.log('[LOGIN] Starting authentication...');
-      const result = await authClient.signIn.email({
-        email,
-        password,
-        callbackURL: callbackUrl,
-      });
-
-      if ((result as any)?.error) {
-        console.log('[LOGIN] Authentication failed:', (result as any).error);
-
-        setIsSubmitting(false);
-        setLoading(false);
-        setLoginSuccess(false);
-
-        const errorMsg = typeof (result as any).error === 'object'
-          ? ((result as any).error as any).message || 'Authentication failed'
-          : String((result as any).error);
-
-        if (errorMsg.includes('password') || errorMsg.includes('Password')) {
-          console.log('[LOGIN] Password error detected - showing recovery options');
-          setShowRecoveryOptions(true);
-          setLoginError(errorMsg);
-        } else if (errorMsg.includes('Unable to connect')) {
-          setLoginError('The authentication service is currently unavailable. Please try again later.');
-        } else {
-          setLoginError(errorMsg);
-        }
-        return;
-      }
-
-      // Atomic state: set to success
-      console.log('[LOGIN] Authentication successful!');
-      setLoginSuccess(true);
-      setLoginError(null);
-      setIsSubmitting(false);
-
-      // Get updated session
-      const freshSession = await authClient.getSession();
-      console.log('[LOGIN] Fresh session obtained, redirecting to 2FA...');
-
-      // Redirect to verify-code for 2FA
-      const verifyUrl = `/account-auth/verify-code?callbackUrl=${encodeURIComponent(callbackUrl)}`;
-      console.log('[LOGIN] Redirecting to:', verifyUrl);
-      window.location.href = verifyUrl;
-
-    } catch (err) {
-      console.error('[LOGIN] Unexpected error:', err);
-
-      // Atomic state: set to error
-      setIsSubmitting(false);
-      setLoading(false);
-      setLoginSuccess(false);
-      setLoginError(err instanceof Error ? err.message : 'An error occurred during login');
-    }
-  };
+  // handleSubmit REMOVED with the email/password form it served: it called
+  // authClient.signIn.email, which better-auth always rejected because this
+  // package never configures emailAndPassword. See the note at the render site.
 
   // Show loading spinner for initial loads
   if (!forceShowForm && !loginError && (loading || (status === 'loading' && !session))) {
@@ -246,169 +242,62 @@ function LoginForm() {
             </p>
           </div>
 
-          {/* Login Form */}
-          <form onSubmit={handleSubmit} className="space-y-6" data-testid="login-form">
-            {/* Email Field */}
-            <div>
-              <label htmlFor="email" className="block text-sm font-medium mb-2" style={{ color: 'inherit' }}>
-                Email Address
-              </label>
-              <input
-                id="email"
-                type="email"
-                required
-                autoFocus
-                autoComplete="email"
-                value={email}
-                onChange={(e) => setEmail(e.target.value)}
-                className={`themed-input w-full px-4 py-3 border border-gray-300 rounded-lg transition-colors`}
-                placeholder="you@example.com"
-                disabled={isSubmitting}
+          {/* Social sign-in — rendered ONLY from the IDP client config's
+              enabled providers (see the /api/auth/settings discovery above).
+              Above the form, divider idiom per the package's ModeAwareLoginPage. */}
+          {googleEnabled && (
+            <>
+              <button
+                type="button"
+                onClick={() => void handleGoogleSignIn()}
+                disabled={googleLoading || isSubmitting}
+                data-testid="google-sign-in"
+                className="w-full px-4 py-3 mb-6 rounded-lg border border-gray-300 font-semibold transition-colors flex items-center justify-center gap-2 disabled:opacity-50 disabled:cursor-not-allowed hover:bg-gray-50"
                 style={{ backgroundColor: 'white', color: '#1f2937' }}
-              />
-            </div>
-
-            {/* Password Field with Show/Hide Toggle */}
-            <div>
-              <label htmlFor="password" className="block text-sm font-medium mb-2" style={{ color: 'inherit' }}>
-                Password
-              </label>
-              <div className="relative">
-                <input
-                  id="password"
-                  type={showPassword ? "text" : "password"}
-                  required
-                  autoComplete="current-password"
-                  value={password}
-                  onChange={(e) => setPassword(e.target.value)}
-                  className={`themed-input w-full px-4 py-3 pr-12 border border-gray-300 rounded-lg transition-colors`}
-                  placeholder="••••••••"
-                  disabled={isSubmitting}
-                  style={{ backgroundColor: 'white', color: '#1f2937' }}
-                />
-                <button
-                  type="button"
-                  onClick={() => setShowPassword(!showPassword)}
-                  className="absolute right-3 top-1/2 transform -translate-y-1/2 hover:opacity-70"
-                  style={{ color: 'inherit', opacity: 0.7 }}
-                  aria-label={showPassword ? "Hide password" : "Show password"}
-                >
-                  {showPassword ? (
-                    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" className="w-5 h-5">
-                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13.875 18.825A10.05 10.05 0 0112 19c-4.478 0-8.268-2.943-9.543-7a9.97 9.97 0 011.563-3.029m5.858.908a3 3 0 114.243 4.243M9.878 9.878l4.242 4.242M9.878 9.878L6.464 6.464m7.535 7.535l3.415 3.414M3 3l3.464 3.464M21 21l-3.415-3.414" />
-                    </svg>
-                  ) : (
-                    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" className="w-5 h-5">
-                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" />
-                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M2.458 12C3.732 7.943 7.523 5 12 5c4.478 0 8.268 2.943 9.542 7-1.274 4.057-5.064 7-9.542 7-4.477 0-8.268-2.943-9.542-7z" />
-                    </svg>
-                  )}
-                </button>
-              </div>
-            </div>
-
-            {/* Atomic Status Display - Deterministic Reserved Space (zero layout shift) */}
-            <ReservedStatusBox
-              candidates={[
-                "Ready",
-                "Authenticating...",
-                "The authentication service is currently unavailable. Please try again later.",
-                "Invalid email or password. Please try again.",
-                "Login successful! Redirecting..."
-              ]}
-              containerClass="p-3 text-sm leading-relaxed rounded-lg border"
-              iconSizePx={16}
-            >
-              {isSubmitting ? (
-                /* Themed: Submitting */
-                <div className="themed-status-submitting flex items-start space-x-2 p-3 rounded-lg">
-                  <svg className="animate-spin w-4 h-4 mt-0.5 flex-shrink-0" fill="none" viewBox="0 0 24 24" style={{ color: buttonColor }}>
-                    <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4"></circle>
-                    <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+              >
+                {googleLoading ? (
+                  <svg className="animate-spin w-5 h-5" fill="none" viewBox="0 0 24 24">
+                    <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+                    <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8v4a4 4 0 00-4 4H4z" />
                   </svg>
-                  <span className="themed-status-submitting-text text-sm leading-relaxed" style={{ color: buttonColor }}>Authenticating...</span>
-                </div>
-              ) : loginError ? (
-                /* Red: Error */
-                <div className="flex items-start space-x-2 p-3 rounded-lg bg-red-500/10 border border-red-500/20">
-                  <div className="w-4 h-4 bg-red-500 rounded-full mt-0.5 flex-shrink-0"></div>
-                  <span className="text-red-600 text-sm leading-relaxed">{loginError}</span>
-                </div>
-              ) : loginSuccess ? (
-                /* Green: Success */
-                <div className="flex items-start space-x-2 p-3 rounded-lg bg-green-500/10 border border-green-500/20">
-                  <div className="w-4 h-4 bg-green-500 rounded-full mt-0.5 flex-shrink-0"></div>
-                  <span className="text-green-600 text-sm leading-relaxed">Login successful! Redirecting...</span>
-                </div>
-              ) : (
-                /* Ready State / Health Check Placeholder */
-                <div className="flex items-start space-x-2 p-3 rounded-lg bg-green-500/10 border border-green-500/20">
-                  <div className="w-4 h-4 bg-green-500 rounded-full mt-0.5 flex-shrink-0"></div>
-                  <span className="text-green-600 text-sm leading-relaxed">Ready</span>
-                  {/*
-                    CUSTOMIZATION: Replace above with your health check component
-                    Example: <SignalRHealthCheck />
-                    Or any real-time health status component
-                  */}
-                </div>
-              )}
-            </ReservedStatusBox>
-
-            {/* Account Recovery Options - Deterministic Reserved Space (zero layout shift) */}
-            <ReservedRecoveryWarning
-              show={showRecoveryOptions}
-              titleText="Account Lockout Warning"
-              bodyText="Your account will be locked after one more failed attempt. Need help?"
-              actionLabel="Start Account Recovery"
-              containerClass="p-4 bg-amber-50 border border-amber-200 rounded-lg"
-              titleClass="text-amber-900 font-medium mb-2"
-              bodyClass="text-amber-800 text-sm mb-3"
-              buttonClass="w-full bg-amber-600 hover:bg-amber-700 text-white font-medium py-2 px-4 rounded-md text-sm transition-colors"
-              iconSizePx={20}
-            >
-              {showRecoveryOptions && (
-                <div className="p-4 bg-amber-50 border border-amber-200 rounded-lg">
-                  <div className="flex items-start space-x-3">
-                    <svg className="w-5 h-5 text-amber-600 mt-0.5 flex-shrink-0" fill="currentColor" viewBox="0 0 20 20">
-                      <path fillRule="evenodd" d="M8.257 3.099c.765-1.36 2.722-1.36 3.486 0l5.58 9.92c.75 1.334-.213 2.98-1.742 2.98H4.42c-1.53 0-2.493-1.646-1.743-2.98l5.58-9.92zM11 13a1 1 0 11-2 0 1 1 0 012 0zm-1-8a1 1 0 00-1 1v3a1 1 0 002 0V6a1 1 0 00-1-1z" clipRule="evenodd" />
-                    </svg>
-                    <div className="flex-1">
-                      <h3 className="text-amber-900 font-medium mb-2">Account Lockout Warning</h3>
-                      <p className="text-amber-800 text-sm mb-3">
-                        Your account will be locked after one more failed attempt. Need help?
-                      </p>
-                      <button
-                        type="button"
-                        onClick={() => window.location.href = `/account-auth/recovery?email=${encodeURIComponent(email)}`}
-                        className="w-full bg-amber-600 hover:bg-amber-700 text-white font-medium py-2 px-4 rounded-md text-sm transition-colors"
-                      >
-                        Start Account Recovery
-                      </button>
-                    </div>
-                  </div>
-                </div>
-              )}
-            </ReservedRecoveryWarning>
-
-            {/* Submit Button */}
-            <button
-              type="submit"
-              disabled={isSubmitting}
-              className="themed-button w-full text-white font-semibold py-3 px-4 rounded-lg transition-colors disabled:opacity-50 disabled:cursor-not-allowed flex items-center justify-center"
-            >
-              {isSubmitting ? (
-                <>
-                  <svg className="animate-spin -ml-1 mr-3 h-5 w-5 text-white" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
-                    <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4"></circle>
-                    <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+                ) : (
+                  <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor">
+                    <path d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z" fill="#4285F4"/>
+                    <path d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z" fill="#34A853"/>
+                    <path d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z" fill="#FBBC05"/>
+                    <path d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z" fill="#EA4335"/>
                   </svg>
-                  Signing in...
-                </>
-              ) : (
-                'Sign In'
-              )}
-            </button>
-          </form>
+                )}
+                {googleLoading ? 'Redirecting to Google…' : 'Continue with Google'}
+              </button>
+            </>
+          )}
+
+          {/* EMAIL/PASSWORD FORM REMOVED — the package has NEVER implemented it.
+              `emailAndPassword` appears ZERO times in src/ and dist/: better-auth.ts
+              configures socialProviders only, so authClient.signIn.email always
+              returned "Email and password is not enabled". The form was a dead
+              control on the first screen of every consumer, and no consumer could
+              enable it without forking. Removed 2026-08-02 (Jon via BAPert 17586).
+              To ADD password auth later: set emailAndPassword in better-auth.ts and
+              restore this form together — one without the other is what created this. */}
+
+          {/* ALTERNATE SIGN-IN SLOT — the "B2 slot" (card 169071).
+              ─────────────────────────────────────────────────────────────
+              Consumers with an extra sign-in route (today: passkey) rendered
+              it AFTER <LoginPage/> as a sibling, which put the control BELOW
+              THE FOLD, because this page owns `min-h-screen` centering. The
+              graft's own comment called that "knowingly ugly and knowingly
+              temporary" and named the fix: give LoginPage a slot.
+
+              It sits here — after the social row, before the footer links —
+              so an alternate method reads as a peer of "Continue with
+              Google" rather than as an afterthought below the card.
+
+              A SLOT, not a passkey prop: this page must not know what a
+              passkey is. The consumer owns the control and its ceremony;
+              the package owns only where it goes. */}
+          {altAuthSlot && <div className="mt-4">{altAuthSlot}</div>}
 
           {/* Footer Links */}
           <div className={`mt-6 text-center text-sm ${colors.muted}`}>
@@ -447,10 +336,16 @@ function LoginPageFallback() {
   );
 }
 
-export default function LoginPage() {
+/**
+ * @param altAuthSlot an additional sign-in control (e.g. a passkey link)
+ *   rendered INSIDE the card, after the social row. Optional: omitting it
+ *   leaves the page byte-identical to before, so existing consumers are
+ *   unaffected.
+ */
+export default function LoginPage({ altAuthSlot }: { altAuthSlot?: React.ReactNode } = {}) {
   return (
     <Suspense fallback={<LoginPageFallback />}>
-      <LoginForm />
+      <LoginForm altAuthSlot={altAuthSlot} />
     </Suspense>
   );
 }

package/src/pages/security/EnhancedSecurityPage.tsx

@@ -200,9 +200,9 @@ export default function EnhancedSecurityPage() {
   const layout = useLayout();
   const colors = useColors();
 
-  // Re-auth action types (moved for scope)
-type ReAuthAction = 'enable_2fa' | 'disable_2fa' | 'export_data' | 'delete_account' | null;
-
+  // Re-auth action types (moved for scope)
+type ReAuthAction = 'enable_2fa' | 'disable_2fa' | 'export_data' | 'delete_account' | null;
+
   // Security data state (would come from API in production)
   const [securityData, setSecurityData] = useState<SecurityData | null>(null);
   const [loadingSecurityData, setLoadingSecurityData] = useState(true);
@@ -218,12 +218,12 @@ type ReAuthAction = 'enable_2fa' | 'disable_2fa' | 'export_data' | 'delete_accou
     new_password: '',
     confirm_password: '',
   });
-  const [showPasswords, setShowPasswords] = useState({ current: false, new: false, confirm: false });
-
-  // Re-authentication modal state (Security Addendum)
-  const [reAuthModal, setReAuthModal] = useState<{
-    isOpen: boolean;
-    action: ReAuthAction;
+  const [showPasswords, setShowPasswords] = useState({ current: false, new: false, confirm: false });
+
+  // Re-authentication modal state (Security Addendum)
+  const [reAuthModal, setReAuthModal] = useState<{
+    isOpen: boolean;
+    action: ReAuthAction;
   }>({ isOpen: false, action: null });
   const [submitting, setSubmitting] = useState(false);
   const [error, setError] = useState('');

package/src/pages/verify-code/page.tsx

@@ -49,7 +49,7 @@ interface MaskedInfo {
   has_authenticator?: boolean;
 }
 
-function VerifyCodeForm() {
+function VerifyCodeForm({ enrollHref }: { enrollHref: string }) {
   const router = useRouter();
   const searchParams = useSearchParams();
   const callbackUrl = searchParams?.get('callbackUrl') || '/dashboard';
@@ -193,7 +193,36 @@ function VerifyCodeForm() {
         const res = await fetch('/api/session/viability', {
           credentials: 'include',
         });
-        
+
+        // ====================================================================
+        // THE ENROLMENT DEAD END (cards 170045 / 170047, was 141688 / 141741)
+        // ====================================================================
+        // A first-time social user arrives here with ZERO usable methods and is
+        // asked for a code from an authenticator that does not exist. There was
+        // no way out: not a missing feature, AN UNASKED QUESTION.
+        //
+        // The IDP already decides this and says so. The package already relays
+        // it — from BOTH viability exports, deliberately, so an app mounting
+        // either is not left blind. The graft already mounts the route. THIS
+        // PAGE ALREADY CALLS IT, four lines above. It simply never read the
+        // answer: the only branch was `res.status === 401`, so on a perfectly
+        // valid session the response was fetched and thrown away.
+        //
+        //   'enroll_mfa'  no USABLE method — the user CANNOT complete a
+        //                 challenge, so keeping them on a code prompt is a trap
+        //   'mfa_verify'  a usable method exists — the prompt is correct
+        //   null          nothing due
+        //
+        // Every link in that chain was built against these very cards. The
+        // last consumer just never asked.
+        if (res.ok) {
+          const data = await res.json().catch(() => ({}));
+          if (data?.nextStep === 'enroll_mfa') {
+            router.replace(enrollHref);
+            return;
+          }
+        }
+
         if (res.status === 401) {
           const data = await res.json().catch(() => ({}));
           
@@ -223,7 +252,37 @@ function VerifyCodeForm() {
       clearTimeout(initialTimeout);
       clearInterval(interval);
     };
-  }, [status, router]);
+  }, [status, router, enrollHref]);
+
+  // ==========================================================================
+  // Enrolment dead-end check — IMMEDIATE, and deliberately separate
+  // ==========================================================================
+  // The poller above first fires after 5 SECONDS. For expiry that is fine. For
+  // a user who can never complete this challenge it is five seconds of staring
+  // at an unanswerable prompt, which is the whole complaint in card 170045.
+  //
+  // This runs at once — but it is a SEPARATE effect rather than removing the
+  // 5s delay, because that delay guards the 401 path against racing session
+  // establishment immediately after sign-in. Firing the expiry logic instantly
+  // could sign a user out for having a session that is merely still settling.
+  // So: this reads ONLY the 200 body and ONLY routes on 'enroll_mfa'. It never
+  // signs anyone out, so it is safe to run with no delay.
+  useEffect(() => {
+    if (status !== 'authenticated') return;
+    let cancelled = false;
+    (async () => {
+      try {
+        const res = await fetch('/api/session/viability', { credentials: 'include' });
+        if (!res.ok || cancelled) return;
+        const data = await res.json().catch(() => ({}));
+        if (data?.nextStep === 'enroll_mfa') router.replace(enrollHref);
+      } catch {
+        // Silent: the poller and the next real API call both still cover this.
+        // A failed check must leave the user on the prompt, never redirect them.
+      }
+    })();
+    return () => { cancelled = true; };
+  }, [status, router, enrollHref]);
 
   const handleSendCode = async (selectedMethod: 'email' | 'sms') => {
     setSending(true);
@@ -643,10 +702,17 @@ function VerifyCodePageFallback() {
   );
 }
 
-export default function VerifyCodePage() {
+/**
+ * @param enrollHref where a user with NO usable 2FA method is sent to enrol.
+ *   Defaults to `/account/security`, which is where the enrolment surface
+ *   lives in the admin graft. It is a PROP rather than a constant because the
+ *   mount path is the consumer's choice — the package must not assume another
+ *   app's routing table.
+ */
+export default function VerifyCodePage({ enrollHref = '/account/security' }: { enrollHref?: string } = {}) {
   return (
     <Suspense fallback={<VerifyCodePageFallback />}>
-      <VerifyCodeForm />
+      <VerifyCodeForm enrollHref={enrollHref} />
     </Suspense>
   );
 }

package/src/routes/account/index.ts

@@ -1,32 +1,32 @@
-/**
- * Account Route Exports
- *
- * Provides ready-to-use route exports for all 2FA/account management endpoints.
- * These routes handle the complete 2FA flow with zero configuration.
- *
- * @example
- * ```typescript
- * // Import individual routes
- * export { POST } from '@payez/next-mvp/routes/account/masked-info';
- * export { POST } from '@payez/next-mvp/routes/account/send-code';
- * export { POST } from '@payez/next-mvp/routes/account/verify-email';
- * export { POST } from '@payez/next-mvp/routes/account/verify-sms';
- * ```
- *
- * @version 2.3.0
- * @since auth-ready-v2
- */
-
-// Export individual route modules
-export * as maskedInfo from './masked-info';
-export * as sendCode from './send-code';
-export * as verifyEmail from './verify-email';
-export * as verifySms from './verify-sms';
-export * as updatePhone from './update-phone';
-
-// Re-export POST handlers for convenience (all 2FA endpoints use POST)
-export { POST as maskedInfoPOST } from './masked-info';
-export { POST as sendCodePOST } from './send-code';
-export { POST as verifyEmailPOST } from './verify-email';
-export { POST as verifySmsPOST } from './verify-sms';
+/**
+ * Account Route Exports
+ *
+ * Provides ready-to-use route exports for all 2FA/account management endpoints.
+ * These routes handle the complete 2FA flow with zero configuration.
+ *
+ * @example
+ * ```typescript
+ * // Import individual routes
+ * export { POST } from '@payez/next-mvp/routes/account/masked-info';
+ * export { POST } from '@payez/next-mvp/routes/account/send-code';
+ * export { POST } from '@payez/next-mvp/routes/account/verify-email';
+ * export { POST } from '@payez/next-mvp/routes/account/verify-sms';
+ * ```
+ *
+ * @version 2.3.0
+ * @since auth-ready-v2
+ */
+
+// Export individual route modules
+export * as maskedInfo from './masked-info';
+export * as sendCode from './send-code';
+export * as verifyEmail from './verify-email';
+export * as verifySms from './verify-sms';
+export * as updatePhone from './update-phone';
+
+// Re-export POST handlers for convenience (all 2FA endpoints use POST)
+export { POST as maskedInfoPOST } from './masked-info';
+export { POST as sendCodePOST } from './send-code';
+export { POST as verifyEmailPOST } from './verify-email';
+export { POST as verifySmsPOST } from './verify-sms';
 export { POST as updatePhonePOST } from './update-phone';