@payez/next-mvp 4.1.10 → 4.1.20

package/dist/lib/session-store.js

@@ -135,6 +135,13 @@ async function getBetterAuthSession(sessionToken, appSlug) {
                 idpRefreshToken: data.idpTokens?.idpRefreshToken,
                 idpAccessTokenExpires: data.idpTokens?.idpAccessTokenExpires,
                 mfaVerified: data.idpTokens?.mfaVerified ?? false,
+                // Cards 141688/141741 — the IDP's routing decision, carried not derived.
+                // `null` is a real value here (IDP said nothing is outstanding), so it
+                // must stay distinguishable from `undefined` (we never captured it —
+                // true of every session minted before this change). No `?? null`:
+                // defaulting would turn "unknown" into "fully authenticated" and
+                // fail open on the existing session population.
+                nextStep: data.idpTokens?.nextStep,
                 roles: data.idpTokens?.roles || [],
                 idpClientId: data.idpTokens?.idpClientId ?? data.idpTokens?.clientId ?? data.idpClientId,
                 merchantId: data.idpTokens?.merchantId ?? data.merchantId,
@@ -489,27 +496,27 @@ async function releaseRefreshLock(sessionToken, requestId, lockVersion) {
     const lockKey = getRefreshLockKey(sessionToken);
     try {
         // Lua script for atomic lock validation and release
-        const luaScript = `
-      local lockKey = KEYS[1]
-      local expectedRequestId = ARGV[1]
-      local expectedVersion = ARGV[2]
-
-      local lockData = redis.call('GET', lockKey)
-      if not lockData then
-        return 0  -- Lock doesn't exist
-      end
-
-      local lockInfo = cjson.decode(lockData)
-      if lockInfo.acquiredBy == expectedRequestId then
-        if not expectedVersion or expectedVersion == '' or tostring(lockInfo.lockVersion) == expectedVersion then
-          redis.call('DEL', lockKey)
-          return 1  -- Successfully released
-        else
-          return -2  -- Version mismatch
-        end
-      else
-        return -1  -- Wrong owner
-      end
+        const luaScript = `
+      local lockKey = KEYS[1]
+      local expectedRequestId = ARGV[1]
+      local expectedVersion = ARGV[2]
+
+      local lockData = redis.call('GET', lockKey)
+      if not lockData then
+        return 0  -- Lock doesn't exist
+      end
+
+      local lockInfo = cjson.decode(lockData)
+      if lockInfo.acquiredBy == expectedRequestId then
+        if not expectedVersion or expectedVersion == '' or tostring(lockInfo.lockVersion) == expectedVersion then
+          redis.call('DEL', lockKey)
+          return 1  -- Successfully released
+        else
+          return -2  -- Version mismatch
+        end
+      else
+        return -1  -- Wrong owner
+      end
     `;
         const result = await redis_1.default.eval(luaScript, 1, lockKey, requestId, lockVersion ? lockVersion.toString() : '');
         if (result === 1) {

package/dist/lib/startup-init.js

@@ -213,25 +213,25 @@ async function performInitialization() {
         const connectionLine = isConnectionError
             ? '║   🔌 CONNECTION REFUSED - IDP appears to be down             ║\n║                                                              ║\n'
             : '';
-        console.error(`
-╔══════════════════════════════════════════════════════════════╗
-║   ❌ FATAL: BETTER_AUTH_SECRET NOT AVAILABLE                  ║
-║                                                              ║
-║   The app cannot start without a valid auth signing secret.  ║
-║   This should be fetched from IDP at startup.                ║
-║                                                              ║
-${connectionLine}║   Possible causes:                                           ║
-║   • IDP is not running or unreachable                        ║
-║   • CLIENT_ID is not registered in IDP                       ║
-║   • IDP_URL is incorrect                                     ║
-║   • Network connectivity issue                               ║
-║                                                              ║
-║   Current config:                                            ║
-║   • IDP_URL: ${idpUrl}║
-║   • CLIENT_ID: ${clientId}║
-╚══════════════════════════════════════════════════════════════╝
-
-[STARTUP] Error: ${errorMsg}
+        console.error(`
+╔══════════════════════════════════════════════════════════════╗
+║   ❌ FATAL: BETTER_AUTH_SECRET NOT AVAILABLE                  ║
+║                                                              ║
+║   The app cannot start without a valid auth signing secret.  ║
+║   This should be fetched from IDP at startup.                ║
+║                                                              ║
+${connectionLine}║   Possible causes:                                           ║
+║   • IDP is not running or unreachable                        ║
+║   • CLIENT_ID is not registered in IDP                       ║
+║   • IDP_URL is incorrect                                     ║
+║   • Network connectivity issue                               ║
+║                                                              ║
+║   Current config:                                            ║
+║   • IDP_URL: ${idpUrl}║
+║   • CLIENT_ID: ${clientId}║
+╚══════════════════════════════════════════════════════════════╝
+
+[STARTUP] Error: ${errorMsg}
 `);
         // Re-throw so callers know initialization failed
         throw lastInitError;

package/dist/lib/token-lifecycle.d.ts

@@ -31,6 +31,8 @@ export interface TokenError {
     error: 'NO_SESSION' | 'NO_TOKEN' | 'EXPIRED' | 'REFRESH_FAILED' | 'SESSION_EXPIRED_NO_REFRESH';
     message: string;
     terminal?: boolean;
+    code?: string;
+    resolution?: string;
 }
 export type EnsureFreshTokenResult = TokenResult | TokenError;
 /**

package/dist/lib/token-lifecycle.js

@@ -150,7 +150,16 @@ async function triggerRefresh(request, sessionToken, retryCount = 0) {
             // Don't retry - user must re-authenticate
             if (responseData.code === 'NO_REFRESH_TOKEN' || responseData.terminal === true) {
                 console.error('[TOKEN_LIFECYCLE] TERMINAL: Session has no refresh token - user must re-login');
-                return { success: false, terminal: true, code: responseData.code };
+                // WO-1: preserve the verbatim upstream reason. refresh.ts puts the human
+                // message in `error` and the code in `code`; carry both up so the consumer
+                // can tell the user WHY (not just "session expired") and stop a futile loop.
+                return {
+                    success: false,
+                    terminal: true,
+                    code: responseData.code,
+                    message: responseData.error,
+                    resolution: responseData.resolution,
+                };
             }
             // For other 401s, check if maybe session was refreshed by another request
             if (response.status === 401 && retryCount < maxRetries) {
@@ -241,8 +250,35 @@ async function ensureFreshToken(request) {
                         idpRefreshToken: idpTokens?.idpRefreshToken,
                         idpAccessTokenExpires: idpTokens?.idpAccessTokenExpires
                             || (baSession.session?.expiresAt ? new Date(baSession.session.expiresAt).getTime() : Date.now() + 24 * 60 * 60 * 1000),
-                        mfaVerified: true,
-                        oauthProvider: 'google',
+                        /**
+                         * ⚠ THESE WERE HARDCODED `true` / `'google'`. (QAPert finding #3,
+                         * BAPert ruling, card 167892.)
+                         *
+                         * This rebuild path assumed EVERY session is a Google OAuth sign-in
+                         * that completed MFA. It reads `idpTokens` for everything else —
+                         * including roles, two lines up — and then IGNORED the stored
+                         * mfaVerified sitting in that same object and asserted `true`.
+                         *
+                         * WHY IT MATTERS MORE THAN A WRONG FIELD: a passkey sign-in stores
+                         * an HONEST mfaVerified derived from the token's `amr`. On any
+                         * Redis miss this path OVERWROTE that false with true — so the
+                         * session claimed an MFA the user never performed, and the honest
+                         * derivation upstream was not weakened but VOIDED. Same defect
+                         * class as the mints that assert completion they never did,
+                         * arriving through a cache-miss rather than a mint.
+                         *
+                         * `oauthProvider: 'google'` was the second lie on the same line:
+                         * a passkey session rebuilt here was relabelled a Google sign-in,
+                         * destroying the provenance the sign-in path deliberately records.
+                         * The IDP emits NO provider claim (DotNetPert), so the honest
+                         * answer when it was not stored is UNSET — not a guess.
+                         *
+                         * Both now default to the SAFE direction: absent/false is
+                         * fail-closed at every consumer we measured (`!!mfaVerified`,
+                         * `mfaVerified || ... || false`).
+                         */
+                        mfaVerified: idpTokens?.mfaVerified ?? false,
+                        oauthProvider: idpTokens?.oauthProvider ?? baSession.oauthProvider ?? undefined,
                         idpClientId: idpTokens?.idpClientId ?? idpTokens?.clientId ?? baSession.idpClientId,
                         merchantId: idpTokens?.merchantId ?? baSession.merchantId,
                     };
@@ -258,8 +294,17 @@ async function ensureFreshToken(request) {
                 name: betterAuthSession.user.name,
                 roles: [],
                 idpAccessTokenExpires: Date.now() + 24 * 60 * 60 * 1000,
-                mfaVerified: true,
-                oauthProvider: 'google',
+                /**
+                 * ⚠ ALSO HARDCODED `true` / `'google'`, and this path is the worse of
+                 * the two: it runs with NO IDP TOKENS AT ALL — the comment above says
+                 * so — and still asserted that MFA was completed. It fabricated an
+                 * assurance claim from nothing, for every consumer, not just passkey.
+                 *
+                 * With nothing to derive from, FALSE is the only honest value and
+                 * UNSET is the only honest provider. Both are fail-closed.
+                 */
+                mfaVerified: false,
+                oauthProvider: undefined,
             };
         }
         if (!sessionData) {
@@ -318,12 +363,21 @@ async function ensureFreshToken(request) {
             if (!refreshResult.success) {
                 // Check for terminal state - session cannot be recovered
                 if (refreshResult.terminal) {
-                    console.error('[TOKEN_LIFECYCLE] TERMINAL: Session expired with no refresh token - redirect to login');
+                    console.error('[TOKEN_LIFECYCLE] TERMINAL: Session expired - redirect to login', {
+                        code: refreshResult.code,
+                        message: refreshResult.message,
+                    });
+                    // WO-1: keep `error` as the stable terminal category (existing consumers
+                    // branch on SESSION_EXPIRED_NO_REFRESH) but surface the verbatim upstream
+                    // reason via code/message/resolution so the user learns WHY and a genuinely
+                    // dead session (e.g. unapproved account) doesn't loop login→bounce→login.
                     return {
                         success: false,
                         error: 'SESSION_EXPIRED_NO_REFRESH',
-                        message: 'Session expired. Please sign in again.',
+                        message: refreshResult.message || 'Session expired. Please sign in again.',
                         terminal: true,
+                        code: refreshResult.code,
+                        resolution: refreshResult.resolution,
                     };
                 }
                 console.warn('[TOKEN_LIFECYCLE] Refresh failed');

package/dist/models/SessionModel.d.ts

@@ -48,6 +48,23 @@ export interface SessionData {
     bearerKeyId?: string;
     /** Whether MFA has been verified for this session */
     mfaVerified: boolean;
+    /**
+     * The IDP's own routing decision for a 2FA-pending login (cards 141688 /
+     * 141741, IDP WO 113023). Wire name is snake — `next_step`.
+     *
+     *   'enroll_mfa'  — no USABLE method (confirmed and not revoked). The user
+     *                   cannot complete a challenge; they must enrol first.
+     *   'mfa_verify'  — a usable method exists; challenge them.
+     *   null          — fully authenticated, nothing outstanding.
+     *
+     * RELAYED, NEVER DERIVED. The IDP owns this fact and is already usable-aware;
+     * recomputing it here from a method count would make a second owner and would
+     * get the revoked-method case wrong (count>0 but usable=0).
+     *
+     * NOT A COMPLETION SIGNAL. 'mfa_verify' means "can be challenged", not
+     * "is through". `mfaVerified` remains the only field that says they verified.
+     */
+    nextStep?: 'enroll_mfa' | 'mfa_verify' | null;
     /** The MFA method used (email, sms, totp) */
     mfaMethod?: 'email' | 'sms' | 'totp';
     /** When MFA was completed (Unix timestamp ms) */

package/dist/pages/login/page.d.ts

@@ -19,4 +19,13 @@
  * 2. Wrap your app with ThemeProvider to customize branding
  * 3. Optionally add your health check component
  */
-export default function LoginPage(): import("react/jsx-runtime").JSX.Element;
+import React from 'react';
+/**
+ * @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;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/pages/login/page.js

@@ -21,9 +21,6 @@
  * 3. Optionally add your health check component
  */
 'use client';
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = LoginPage;
 const jsx_runtime_1 = require("react/jsx-runtime");
@@ -31,19 +28,66 @@ const react_1 = require("react");
 const better_auth_client_1 = require("../../client/better-auth-client");
 const navigation_1 = require("next/navigation");
 const react_2 = require("react");
-const ReservedStatusBox_1 = __importDefault(require("../../components/reserved/ReservedStatusBox"));
-const ReservedRecoveryWarning_1 = __importDefault(require("../../components/reserved/ReservedRecoveryWarning"));
 const useTheme_1 = require("../../theme/useTheme");
-function LoginForm() {
+function LoginForm({ altAuthSlot }) {
     const searchParams = (0, navigation_1.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 } = better_auth_client_1.authClient.useSession();
     const session = sessionData;
     const status = isPending ? 'loading' : session ? 'authenticated' : 'unauthenticated';
     const branding = (0, useTheme_1.useBranding)();
     const colors = (0, useTheme_1.useColors)();
     const layout = (0, useTheme_1.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] = (0, react_1.useState)(false);
+    const [googleLoading, setGoogleLoading] = (0, react_1.useState)(false);
+    (0, react_1.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 = 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 better_auth_client_1.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 better_auth_client_1.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, percent) => {
         const num = parseInt(hex.replace('#', ''), 16);
@@ -71,6 +115,13 @@ function LoginForm() {
     const [showRecoveryOptions, setShowRecoveryOptions] = (0, react_1.useState)(false);
     // Force show form after timeout if stuck in loading
     const [forceShowForm, setForceShowForm] = (0, react_1.useState)(false);
+    // Surface OAuth failures the Better Auth mount bounced back here.
+    (0, react_1.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
     (0, react_1.useEffect)(() => {
         if (urlError) {
@@ -115,63 +166,9 @@ function LoginForm() {
         }, 1000);
         return () => clearTimeout(immediateTimeout);
     }, [status, session]);
-    const handleSubmit = async (e) => {
-        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 better_auth_client_1.authClient.signIn.email({
-                email,
-                password,
-                callbackURL: callbackUrl,
-            });
-            if (result?.error) {
-                console.log('[LOGIN] Authentication failed:', result.error);
-                setIsSubmitting(false);
-                setLoading(false);
-                setLoginSuccess(false);
-                const errorMsg = typeof result.error === 'object'
-                    ? result.error.message || 'Authentication failed'
-                    : String(result.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 better_auth_client_1.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))) {
         return ((0, jsx_runtime_1.jsxs)("div", { className: `flex flex-col items-center justify-center min-h-screen ${colors.background}`, children: [(0, jsx_runtime_1.jsxs)("svg", { className: "animate-spin h-6 w-6", style: { color: buttonColor }, viewBox: "0 0 24 24", fill: "none", children: [(0, jsx_runtime_1.jsx)("circle", { className: "opacity-25", cx: "12", cy: "12", r: "10", stroke: "currentColor", strokeWidth: "4" }), (0, jsx_runtime_1.jsx)("path", { className: "opacity-75", fill: "currentColor", d: "M4 12a8 8 0 018-8v4a4 4 0 00-4 4H4z" })] }), (0, jsx_runtime_1.jsx)("p", { className: `mt-4 text-sm ${colors.muted}`, children: status === 'loading' ? 'Loading...' : 'Authenticating...' })] }));
@@ -204,27 +201,19 @@ function LoginForm() {
         .themed-status-submitting svg {
           color: ${buttonColor} !important;
         }
-      ` } }), (0, jsx_runtime_1.jsx)("div", { className: `min-h-screen flex items-center justify-center px-4 ${colors.background}`, children: (0, jsx_runtime_1.jsxs)("div", { className: "max-w-md w-full", children: [(0, jsx_runtime_1.jsxs)("div", { className: `rounded-2xl shadow-xl p-8 ${colors.card} ${colors.border} text-gray-800`, children: [(0, jsx_runtime_1.jsxs)("div", { className: "text-center mb-8", children: [(0, jsx_runtime_1.jsx)("h1", { className: "text-3xl font-bold mb-2", style: { color: 'inherit' }, children: branding.tagline || 'Welcome Back' }), (0, jsx_runtime_1.jsx)("p", { className: colors.muted, children: "Sign in to your account" })] }), (0, jsx_runtime_1.jsxs)("form", { onSubmit: handleSubmit, className: "space-y-6", "data-testid": "login-form", children: [(0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("label", { htmlFor: "email", className: "block text-sm font-medium mb-2", style: { color: 'inherit' }, children: "Email Address" }), (0, jsx_runtime_1.jsx)("input", { id: "email", type: "email", required: true, autoFocus: true, 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, style: { backgroundColor: 'white', color: '#1f2937' } })] }), (0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("label", { htmlFor: "password", className: "block text-sm font-medium mb-2", style: { color: 'inherit' }, children: "Password" }), (0, jsx_runtime_1.jsxs)("div", { className: "relative", children: [(0, jsx_runtime_1.jsx)("input", { id: "password", type: showPassword ? "text" : "password", required: true, 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: "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022", disabled: isSubmitting, style: { backgroundColor: 'white', color: '#1f2937' } }), (0, jsx_runtime_1.jsx)("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", children: showPassword ? ((0, jsx_runtime_1.jsx)("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", className: "w-5 h-5", children: (0, jsx_runtime_1.jsx)("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" }) })) : ((0, jsx_runtime_1.jsxs)("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", className: "w-5 h-5", children: [(0, jsx_runtime_1.jsx)("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M15 12a3 3 0 11-6 0 3 3 0 016 0z" }), (0, jsx_runtime_1.jsx)("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" })] })) })] })] }), (0, jsx_runtime_1.jsx)(ReservedStatusBox_1.default, { 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, children: isSubmitting ? (
-                                            /* Themed: Submitting */
-                                            (0, jsx_runtime_1.jsxs)("div", { className: "themed-status-submitting flex items-start space-x-2 p-3 rounded-lg", children: [(0, jsx_runtime_1.jsxs)("svg", { className: "animate-spin w-4 h-4 mt-0.5 flex-shrink-0", fill: "none", viewBox: "0 0 24 24", style: { color: buttonColor }, children: [(0, jsx_runtime_1.jsx)("circle", { className: "opacity-25", cx: "12", cy: "12", r: "10", stroke: "currentColor", strokeWidth: "4" }), (0, jsx_runtime_1.jsx)("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" })] }), (0, jsx_runtime_1.jsx)("span", { className: "themed-status-submitting-text text-sm leading-relaxed", style: { color: buttonColor }, children: "Authenticating..." })] })) : loginError ? (
-                                            /* Red: Error */
-                                            (0, jsx_runtime_1.jsxs)("div", { className: "flex items-start space-x-2 p-3 rounded-lg bg-red-500/10 border border-red-500/20", children: [(0, jsx_runtime_1.jsx)("div", { className: "w-4 h-4 bg-red-500 rounded-full mt-0.5 flex-shrink-0" }), (0, jsx_runtime_1.jsx)("span", { className: "text-red-600 text-sm leading-relaxed", children: loginError })] })) : loginSuccess ? (
-                                            /* Green: Success */
-                                            (0, jsx_runtime_1.jsxs)("div", { className: "flex items-start space-x-2 p-3 rounded-lg bg-green-500/10 border border-green-500/20", children: [(0, jsx_runtime_1.jsx)("div", { className: "w-4 h-4 bg-green-500 rounded-full mt-0.5 flex-shrink-0" }), (0, jsx_runtime_1.jsx)("span", { className: "text-green-600 text-sm leading-relaxed", children: "Login successful! Redirecting..." })] })) : (
-                                            /* Ready State / Health Check Placeholder */
-                                            (0, jsx_runtime_1.jsxs)("div", { className: "flex items-start space-x-2 p-3 rounded-lg bg-green-500/10 border border-green-500/20", children: [(0, jsx_runtime_1.jsx)("div", { className: "w-4 h-4 bg-green-500 rounded-full mt-0.5 flex-shrink-0" }), (0, jsx_runtime_1.jsx)("span", { className: "text-green-600 text-sm leading-relaxed", children: "Ready" })] })) }), (0, jsx_runtime_1.jsx)(ReservedRecoveryWarning_1.default, { 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, children: showRecoveryOptions && ((0, jsx_runtime_1.jsx)("div", { className: "p-4 bg-amber-50 border border-amber-200 rounded-lg", children: (0, jsx_runtime_1.jsxs)("div", { className: "flex items-start space-x-3", children: [(0, jsx_runtime_1.jsx)("svg", { className: "w-5 h-5 text-amber-600 mt-0.5 flex-shrink-0", fill: "currentColor", viewBox: "0 0 20 20", children: (0, jsx_runtime_1.jsx)("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" }) }), (0, jsx_runtime_1.jsxs)("div", { className: "flex-1", children: [(0, jsx_runtime_1.jsx)("h3", { className: "text-amber-900 font-medium mb-2", children: "Account Lockout Warning" }), (0, jsx_runtime_1.jsx)("p", { className: "text-amber-800 text-sm mb-3", children: "Your account will be locked after one more failed attempt. Need help?" }), (0, jsx_runtime_1.jsx)("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", children: "Start Account Recovery" })] })] }) })) }), (0, jsx_runtime_1.jsx)("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", children: isSubmitting ? ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsxs)("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", children: [(0, jsx_runtime_1.jsx)("circle", { className: "opacity-25", cx: "12", cy: "12", r: "10", stroke: "currentColor", strokeWidth: "4" }), (0, jsx_runtime_1.jsx)("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" })] }), "Signing in..."] })) : ('Sign In') })] }), (0, jsx_runtime_1.jsx)("div", { className: `mt-6 text-center text-sm ${colors.muted}`, children: (0, jsx_runtime_1.jsx)("a", { href: "/account-auth/recovery", className: "themed-link hover:underline", children: "Start account recovery" }) })] }), (0, jsx_runtime_1.jsxs)("p", { className: `mt-4 text-center text-sm ${colors.muted}`, children: ["Don't have an account?", ' ', (0, jsx_runtime_1.jsx)("a", { href: "/account-auth/register", className: "themed-link font-medium hover:underline", children: "Sign up" })] })] }) })] }));
+      ` } }), (0, jsx_runtime_1.jsx)("div", { className: `min-h-screen flex items-center justify-center px-4 ${colors.background}`, children: (0, jsx_runtime_1.jsxs)("div", { className: "max-w-md w-full", children: [(0, jsx_runtime_1.jsxs)("div", { className: `rounded-2xl shadow-xl p-8 ${colors.card} ${colors.border} text-gray-800`, children: [(0, jsx_runtime_1.jsxs)("div", { className: "text-center mb-8", children: [(0, jsx_runtime_1.jsx)("h1", { className: "text-3xl font-bold mb-2", style: { color: 'inherit' }, children: branding.tagline || 'Welcome Back' }), (0, jsx_runtime_1.jsx)("p", { className: colors.muted, children: "Sign in to your account" })] }), googleEnabled && ((0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: (0, jsx_runtime_1.jsxs)("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' }, children: [googleLoading ? ((0, jsx_runtime_1.jsxs)("svg", { className: "animate-spin w-5 h-5", fill: "none", viewBox: "0 0 24 24", children: [(0, jsx_runtime_1.jsx)("circle", { className: "opacity-25", cx: "12", cy: "12", r: "10", stroke: "currentColor", strokeWidth: "4" }), (0, jsx_runtime_1.jsx)("path", { className: "opacity-75", fill: "currentColor", d: "M4 12a8 8 0 018-8v4a4 4 0 00-4 4H4z" })] })) : ((0, jsx_runtime_1.jsxs)("svg", { className: "w-5 h-5", viewBox: "0 0 24 24", fill: "currentColor", children: [(0, jsx_runtime_1.jsx)("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" }), (0, jsx_runtime_1.jsx)("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" }), (0, jsx_runtime_1.jsx)("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" }), (0, jsx_runtime_1.jsx)("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" })] })), googleLoading ? 'Redirecting to Google…' : 'Continue with Google'] }) })), altAuthSlot && (0, jsx_runtime_1.jsx)("div", { className: "mt-4", children: altAuthSlot }), (0, jsx_runtime_1.jsx)("div", { className: `mt-6 text-center text-sm ${colors.muted}`, children: (0, jsx_runtime_1.jsx)("a", { href: "/account-auth/recovery", className: "themed-link hover:underline", children: "Start account recovery" }) })] }), (0, jsx_runtime_1.jsxs)("p", { className: `mt-4 text-center text-sm ${colors.muted}`, children: ["Don't have an account?", ' ', (0, jsx_runtime_1.jsx)("a", { href: "/account-auth/register", className: "themed-link font-medium hover:underline", children: "Sign up" })] })] }) })] }));
 }
 function LoginPageFallback() {
     const colors = (0, useTheme_1.useColors)();
     const buttonColor = colors.secondary || colors.primary || '#11B588';
     return ((0, jsx_runtime_1.jsx)("div", { className: `min-h-screen flex items-center justify-center ${colors.background}`, children: (0, jsx_runtime_1.jsxs)("div", { className: "text-center", children: [(0, jsx_runtime_1.jsxs)("svg", { className: "animate-spin h-10 w-10 mx-auto", style: { color: buttonColor }, xmlns: "http://www.w3.org/2000/svg", fill: "none", viewBox: "0 0 24 24", children: [(0, jsx_runtime_1.jsx)("circle", { className: "opacity-25", cx: "12", cy: "12", r: "10", stroke: "currentColor", strokeWidth: "4" }), (0, jsx_runtime_1.jsx)("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" })] }), (0, jsx_runtime_1.jsx)("p", { className: `mt-4 ${colors.muted}`, children: "Loading..." })] }) }));
 }
-function LoginPage() {
-    return ((0, jsx_runtime_1.jsx)(react_2.Suspense, { fallback: (0, jsx_runtime_1.jsx)(LoginPageFallback, {}), children: (0, jsx_runtime_1.jsx)(LoginForm, {}) }));
+/**
+ * @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.
+ */
+function LoginPage({ altAuthSlot } = {}) {
+    return ((0, jsx_runtime_1.jsx)(react_2.Suspense, { fallback: (0, jsx_runtime_1.jsx)(LoginPageFallback, {}), children: (0, jsx_runtime_1.jsx)(LoginForm, { altAuthSlot: altAuthSlot }) }));
 }

package/dist/pages/verify-code/page.d.ts

@@ -27,4 +27,13 @@
  * 1. Import from @payez/next-mvp/pages/verify-code
  * 2. Wrap your app with ThemeProvider to customize branding
  */
-export default function VerifyCodePage(): import("react/jsx-runtime").JSX.Element;
+/**
+ * @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 }?: {
+    enrollHref?: string;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/pages/verify-code/page.js

@@ -42,7 +42,7 @@ const useTheme_1 = require("../../theme/useTheme");
  * Prevents auto-redirect back to dashboard when session refreshes in background.
  */
 const VERIFY_IN_PROGRESS_KEY = 'idealvibe_2fa_verify_in_progress';
-function VerifyCodeForm() {
+function VerifyCodeForm({ enrollHref }) {
     const router = (0, navigation_1.useRouter)();
     const searchParams = (0, navigation_1.useSearchParams)();
     const callbackUrl = searchParams?.get('callbackUrl') || '/dashboard';
@@ -166,6 +166,34 @@ 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(() => ({}));
                     // Session is no longer valid - warn user and redirect
@@ -193,7 +221,40 @@ 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.
+    (0, react_1.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) => {
         setSending(true);
         setError(null);
@@ -407,6 +468,13 @@ function VerifyCodePageFallback() {
     const colors = (0, useTheme_1.useColors)();
     return ((0, jsx_runtime_1.jsx)("div", { className: "flex items-center justify-center py-8", style: { background: 'hsl(var(--background))' }, children: (0, jsx_runtime_1.jsxs)("div", { className: "text-center", children: [(0, jsx_runtime_1.jsxs)("svg", { className: "animate-spin h-10 w-10 mx-auto", style: { color: 'hsl(var(--primary))' }, xmlns: "http://www.w3.org/2000/svg", fill: "none", viewBox: "0 0 24 24", children: [(0, jsx_runtime_1.jsx)("circle", { className: "opacity-25", cx: "12", cy: "12", r: "10", stroke: "currentColor", strokeWidth: "4" }), (0, jsx_runtime_1.jsx)("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" })] }), (0, jsx_runtime_1.jsx)("p", { className: "mt-4", style: { color: 'hsl(var(--muted-foreground))' }, children: "Loading..." })] }) }));
 }
-function VerifyCodePage() {
-    return ((0, jsx_runtime_1.jsx)(react_2.Suspense, { fallback: (0, jsx_runtime_1.jsx)(VerifyCodePageFallback, {}), children: (0, jsx_runtime_1.jsx)(VerifyCodeForm, {}) }));
+/**
+ * @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.
+ */
+function VerifyCodePage({ enrollHref = '/account/security' } = {}) {
+    return ((0, jsx_runtime_1.jsx)(react_2.Suspense, { fallback: (0, jsx_runtime_1.jsx)(VerifyCodePageFallback, {}), children: (0, jsx_runtime_1.jsx)(VerifyCodeForm, { enrollHref: enrollHref }) }));
 }

package/dist/routes/auth/passkey-signin.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Ready-to-Use Passkey Sign-In Route (ANONYMOUS ceremony)
+ *
+ * @example
+ * ```typescript
+ * // app/api/passkey/sign-in/options/route.ts
+ * export { POST } from '@payez/next-mvp/routes/auth/passkey-signin';
+ * // (optionsPOST is exported as POST; mount verify at its own path:)
+ * // app/api/passkey/sign-in/verify/route.ts
+ * export { verifyPOST as POST } from '@payez/next-mvp/routes/auth/passkey-signin';
+ * ```
+ */
+export { optionsPOST, verifyPOST } from '../../api-handlers/auth/passkey-signin';