@payez/next-mvp 4.4.9 → 4.5.0

package/dist/pages/onboarding/page.js

@@ -0,0 +1,118 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = OnboardingPage;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const navigation_1 = require("next/navigation");
+const H = { primary: 'var(--text-primary)', secondary: 'var(--text-secondary)', muted: 'var(--text-muted)' };
+function OnboardingContent() {
+    const params = (0, navigation_1.useSearchParams)();
+    const onboardToken = params?.get('onboard_token') ?? '';
+    const [step, setStep] = (0, react_1.useState)('code');
+    const [maskedEmail, setMaskedEmail] = (0, react_1.useState)(null);
+    const [digits, setDigits] = (0, react_1.useState)('');
+    const [password, setPassword] = (0, react_1.useState)('');
+    const [confirm, setConfirm] = (0, react_1.useState)('');
+    const [resetToken, setResetToken] = (0, react_1.useState)('');
+    const [email, setEmail] = (0, react_1.useState)('');
+    const [busy, setBusy] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    // Step 1: tell the invitee which address the code went to (masked). Best
+    // effort - a failure here does not block entering a code they were emailed.
+    (0, react_1.useEffect)(() => {
+        if (!onboardToken)
+            return;
+        let alive = true;
+        (async () => {
+            try {
+                const res = await fetch('/api/onboarding/verify-welcome-email', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ onboard_token: onboardToken }),
+                });
+                const body = await res.json().catch(() => null);
+                const data = body?.data?.data || body?.data || {};
+                const masked = data?.masked_user_info?.masked_email || data?.masked_email;
+                if (alive && typeof masked === 'string' && masked)
+                    setMaskedEmail(masked);
+            }
+            catch { /* non-fatal */ }
+        })();
+        return () => { alive = false; };
+    }, [onboardToken]);
+    if (!onboardToken) {
+        return ((0, jsx_runtime_1.jsxs)(Shell, { children: [(0, jsx_runtime_1.jsx)("h1", { style: titleStyle, children: "This invitation link is missing its token." }), (0, jsx_runtime_1.jsx)("p", { style: { color: H.secondary, fontSize: 14, marginTop: 8 }, children: "The link may have been truncated or copied incompletely. Ask for a new invitation, or sign in if you already have an account." }), (0, jsx_runtime_1.jsx)("p", { style: { marginTop: 16 }, children: (0, jsx_runtime_1.jsx)("a", { href: "/account-auth/login", style: linkStyle, children: "Go to sign in" }) })] }));
+    }
+    async function submitCode(e) {
+        e.preventDefault();
+        setBusy(true);
+        setError(null);
+        try {
+            const res = await fetch('/api/onboarding/verify-code', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ onboard_token: onboardToken, code: digits }),
+            });
+            const body = await res.json().catch(() => null);
+            const data = body?.data?.data || body?.data || body;
+            if (!res.ok || !data?.reset_token || !data?.email)
+                throw new Error();
+            setResetToken(data.reset_token);
+            setEmail(data.email);
+            setStep('password');
+        }
+        catch {
+            setError('That code was not accepted. Check it and try again.');
+        }
+        finally {
+            setBusy(false);
+        }
+    }
+    async function submitPassword(e) {
+        e.preventDefault();
+        if (password !== confirm) {
+            setError('The two passwords do not match.');
+            return;
+        }
+        setBusy(true);
+        setError(null);
+        try {
+            const res = await fetch('/api/onboarding/set-password', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ onboard_token: onboardToken, email, reset_token: resetToken, new_password: password }),
+            });
+            const body = await res.json().catch(() => null);
+            if (!res.ok || (body && body.success === false))
+                throw new Error(body?.message || '');
+            setStep('done');
+        }
+        catch (err) {
+            setError(err instanceof Error && err.message ? err.message : 'We could not set that password. Try again.');
+        }
+        finally {
+            setBusy(false);
+        }
+    }
+    return ((0, jsx_runtime_1.jsxs)(Shell, { children: [step === 'code' && ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("h1", { style: titleStyle, children: "Finish setting up your account" }), (0, jsx_runtime_1.jsx)("p", { style: { color: H.secondary, fontSize: 14, marginTop: 8 }, children: maskedEmail
+                            ? `We emailed a 6-digit code to ${maskedEmail}. Enter it below.`
+                            : 'Enter the 6-digit code from your invitation email.' }), (0, jsx_runtime_1.jsxs)("form", { onSubmit: submitCode, noValidate: true, style: { marginTop: 16 }, children: [(0, jsx_runtime_1.jsx)("input", { value: digits, onChange: (e) => setDigits(e.target.value.replace(/\D/g, '').slice(0, 6)), inputMode: "numeric", autoComplete: "one-time-code", "aria-label": "6-digit code", placeholder: "000000", style: { ...inputStyle, letterSpacing: 6, textAlign: 'center', fontFamily: 'monospace', fontSize: 20 } }), (0, jsx_runtime_1.jsx)("button", { type: "submit", disabled: busy || digits.length < 6, style: ctaStyle(busy || digits.length < 6), children: busy ? 'Verifying…' : 'Verify' })] })] })), step === 'password' && ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("h1", { style: titleStyle, children: "Choose a password" }), (0, jsx_runtime_1.jsx)("p", { style: { color: H.secondary, fontSize: 14, marginTop: 8 }, children: "Set the password you will sign in with." }), (0, jsx_runtime_1.jsxs)("form", { onSubmit: submitPassword, noValidate: true, style: { marginTop: 16 }, children: [(0, jsx_runtime_1.jsx)("input", { type: "password", value: password, onChange: (e) => setPassword(e.target.value), "aria-label": "New password", placeholder: "New password", style: inputStyle }), (0, jsx_runtime_1.jsx)("input", { type: "password", value: confirm, onChange: (e) => setConfirm(e.target.value), "aria-label": "Confirm password", placeholder: "Confirm password", style: { ...inputStyle, marginTop: 10 } }), (0, jsx_runtime_1.jsx)("button", { type: "submit", disabled: busy || !password || !confirm, style: ctaStyle(busy || !password || !confirm), children: busy ? 'Saving…' : 'Set password' })] })] })), step === 'done' && ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("h1", { style: titleStyle, children: "You're all set." }), (0, jsx_runtime_1.jsx)("p", { style: { color: H.secondary, fontSize: 14, marginTop: 8 }, children: "Your account is ready. You can sign in now." }), (0, jsx_runtime_1.jsx)("p", { style: { marginTop: 16 }, children: (0, jsx_runtime_1.jsx)("a", { href: "/account-auth/login", style: linkStyle, children: "Go to sign in" }) })] })), error && (0, jsx_runtime_1.jsx)("p", { style: { color: '#b00020', fontSize: 13, marginTop: 12 }, children: error })] }));
+}
+const titleStyle = { color: H.primary, fontSize: 20, fontWeight: 600, margin: 0 };
+const linkStyle = { color: H.primary, fontWeight: 600, textDecoration: 'underline' };
+const inputStyle = {
+    width: '100%', padding: '10px 12px', border: '1px solid var(--border-default, #d1d5db)',
+    borderRadius: 10, color: H.primary, fontSize: 15, background: 'var(--bg-card, #fff)',
+};
+const ctaStyle = (disabled) => ({
+    marginTop: 14, width: '100%', padding: '10px 12px', borderRadius: 10, border: 'none',
+    background: H.primary, color: '#fff', fontWeight: 600, fontSize: 15, cursor: disabled ? 'default' : 'pointer',
+    opacity: disabled ? 0.5 : 1,
+});
+function Shell({ children }) {
+    return ((0, jsx_runtime_1.jsx)("div", { style: { minHeight: '100vh', display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 16, background: 'var(--bg-default, #f9fafb)' }, children: (0, jsx_runtime_1.jsx)("div", { style: { width: '100%', maxWidth: 420, background: 'var(--bg-card, #fff)', border: '1px solid var(--border-default, #e5e7eb)', borderRadius: 16, padding: 28 }, children: children }) }));
+}
+function OnboardingPage() {
+    return ((0, jsx_runtime_1.jsx)(react_1.Suspense, { fallback: (0, jsx_runtime_1.jsx)("div", { style: { minHeight: '100vh' } }), children: (0, jsx_runtime_1.jsx)(OnboardingContent, {}) }));
+}

package/dist/pages/recovery/page.js

@@ -6,6 +6,7 @@ const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
 const navigation_1 = require("next/navigation");
 const api_1 = require("../../utils/api");
+const password_reset_bridge_1 = require("../../auth/password-reset-bridge");
 const InitiateRecoveryStep_1 = require("../../components/recovery/InitiateRecoveryStep");
 const SelectMethodStep_1 = require("../../components/recovery/SelectMethodStep");
 const VerifyCodeStep_1 = require("../../components/recovery/VerifyCodeStep");
@@ -16,14 +17,18 @@ const useTheme_1 = require("../../theme/useTheme");
 function RecoveryContent() {
     const router = (0, navigation_1.useRouter)();
     const searchParams = (0, navigation_1.useSearchParams)();
-    const prefilledEmail = searchParams?.get('email') || '';
+    // PAY-2121 (BAPert 70576): a VERIFIED passwordless user arrives here with a real
+    // reset token (?token=) from the IdP's post-verify fragment, via the bridge. In
+    // that case skip the request-a-code step and go straight to set-password - the
+    // token is the credential; asking for a code would throw it away.
+    const entry = (0, password_reset_bridge_1.recoveryEntry)(searchParams?.get('token'), searchParams?.get('email'));
     const colors = (0, useTheme_1.useColors)();
-    const [currentStep, setCurrentStep] = (0, react_1.useState)('initiate');
-    const [email, setEmail] = (0, react_1.useState)(prefilledEmail);
+    const [currentStep, setCurrentStep] = (0, react_1.useState)(entry.step);
+    const [email, setEmail] = (0, react_1.useState)(entry.email);
     const [recoverySession, setRecoverySession] = (0, react_1.useState)(null);
     const [selectedMethod, setSelectedMethod] = (0, react_1.useState)(null);
     const [verificationCode, setVerificationCode] = (0, react_1.useState)('');
-    const [passwordResetToken, setPasswordResetToken] = (0, react_1.useState)(null);
+    const [passwordResetToken, setPasswordResetToken] = (0, react_1.useState)(entry.resetToken ? { token: entry.resetToken, expiresAt: '' } : null);
     const [error, setError] = (0, react_1.useState)(null);
     // PAY-1591: true when the reset failed because the recovery itself is dead; the error box then offers a way back.
     const [recoveryExpired, setRecoveryExpired] = (0, react_1.useState)(false);
@@ -108,13 +113,19 @@ function RecoveryContent() {
         }
     };
     const handleResetPassword = async (password, confirmPassword) => {
-        if (!passwordResetToken || !recoverySession)
+        // PAY-2121 (BAPert 70582): the ONE place that decides whether a submit may proceed.
+        // No token (or no email anywhere) -> refuse BEFORE any request; a guard-less submit
+        // would otherwise call the API with an empty token.
+        const target = (0, password_reset_bridge_1.resetSubmitTarget)(passwordResetToken?.token, recoverySession?.email, email);
+        if (!target) {
+            setError(passwordResetToken ? 'We could not tell which account to reset. Start recovery again.' : 'This reset link is missing its token. Start recovery again.');
             return;
+        }
         setLoading(true);
         setError(null);
         setRecoveryExpired(false);
         try {
-            const response = await api_1.accountApi.resetPasswordWithToken(recoverySession.email, passwordResetToken.token, password, confirmPassword);
+            const response = await api_1.accountApi.resetPasswordWithToken(target.email, target.token, password, confirmPassword);
             if (response.success) {
                 setResetSucceeded(true);
                 setCurrentStep('complete');
@@ -136,8 +147,10 @@ function RecoveryContent() {
             setCurrentStep('initiate');
         else if (currentStep === 'verify-code')
             setCurrentStep('select-method');
+        // PAY-2121: a deep-linked set-password has no verify-code to go back to; return to
+        // the request-code step so a bad token still leaves a way forward.
         else if (currentStep === 'set-password')
-            setCurrentStep('verify-code');
+            setCurrentStep(recoverySession ? 'verify-code' : 'initiate');
     };
     return ((0, jsx_runtime_1.jsx)("div", { className: "w-full flex items-center justify-center p-6", style: { background: 'var(--bg-default)' }, children: (0, jsx_runtime_1.jsxs)("div", { className: "max-w-md w-full", children: [error && ((0, jsx_runtime_1.jsxs)("div", { className: "mb-4 bg-red-50 border border-red-200 rounded-2xl p-3", children: [(0, jsx_runtime_1.jsx)("p", { className: "text-red-700 text-sm", children: error }), recoveryExpired && ((0, jsx_runtime_1.jsx)("a", { href: "/account-auth/recovery", className: "text-sm font-medium underline", children: "Start password recovery again" }))] })), loading && ((0, jsx_runtime_1.jsx)("div", { className: "mb-4 rounded-2xl p-3", style: { background: 'var(--bg-card)', borderColor: 'var(--border-default)' }, children: (0, jsx_runtime_1.jsx)("p", { className: "text-sm", style: { color: 'var(--text-secondary)' }, children: "Processing..." }) })), currentStep === 'initiate' && ((0, jsx_runtime_1.jsx)(InitiateRecoveryStep_1.InitiateRecoveryStep, { email: email, setEmail: setEmail, onSubmit: handleInitiateRecovery, loading: loading })), currentStep === 'select-method' && recoverySession && ((0, jsx_runtime_1.jsx)(SelectMethodStep_1.SelectMethodStep, { session: recoverySession, onSelectMethod: handleSendCode, loading: loading })), currentStep === 'verify-code' && ((0, jsx_runtime_1.jsx)(VerifyCodeStep_1.VerifyCodeStep, { code: verificationCode, setCode: setVerificationCode, onSubmit: handleVerifyCode, onResend: () => selectedMethod && handleSendCode(selectedMethod), loading: loading, maskedDestination: selectedMethod === 'sms'
                         ? recoverySession?.maskedPhone

package/dist/routes/onboarding/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Ready-to-use onboarding route handlers (PAY-2121).
+ *
+ * Import directly into your app's API routes with zero configuration:
+ *
+ * @example
+ * ```typescript
+ * // app/api/onboarding/verify-code/route.ts
+ * export { POST } from '@payez/next-mvp/routes/onboarding/verify-code';
+ * ```
+ */
+export { POST as verifyCodePOST } from '../../api-handlers/onboarding/verify-code';
+export { POST as sendEmailCodePOST } from '../../api-handlers/onboarding/send-email-code';
+export { POST as verifyWelcomeEmailPOST } from '../../api-handlers/onboarding/verify-welcome-email';
+export { POST as setPasswordPOST } from '../../api-handlers/onboarding/set-password';

package/dist/routes/onboarding/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setPasswordPOST = exports.verifyWelcomeEmailPOST = exports.sendEmailCodePOST = exports.verifyCodePOST = void 0;
+/**
+ * Ready-to-use onboarding route handlers (PAY-2121).
+ *
+ * Import directly into your app's API routes with zero configuration:
+ *
+ * @example
+ * ```typescript
+ * // app/api/onboarding/verify-code/route.ts
+ * export { POST } from '@payez/next-mvp/routes/onboarding/verify-code';
+ * ```
+ */
+var verify_code_1 = require("../../api-handlers/onboarding/verify-code");
+Object.defineProperty(exports, "verifyCodePOST", { enumerable: true, get: function () { return verify_code_1.POST; } });
+var send_email_code_1 = require("../../api-handlers/onboarding/send-email-code");
+Object.defineProperty(exports, "sendEmailCodePOST", { enumerable: true, get: function () { return send_email_code_1.POST; } });
+var verify_welcome_email_1 = require("../../api-handlers/onboarding/verify-welcome-email");
+Object.defineProperty(exports, "verifyWelcomeEmailPOST", { enumerable: true, get: function () { return verify_welcome_email_1.POST; } });
+var set_password_1 = require("../../api-handlers/onboarding/set-password");
+Object.defineProperty(exports, "setPasswordPOST", { enumerable: true, get: function () { return set_password_1.POST; } });

package/dist/routes/onboarding/send-email-code.d.ts

@@ -0,0 +1,2 @@
+/** POST /api/onboarding/send-email-code -> IdP (PAY-2121). */
+export { POST } from '../../api-handlers/onboarding/send-email-code';

package/dist/routes/onboarding/send-email-code.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+/** POST /api/onboarding/send-email-code -> IdP (PAY-2121). */
+var send_email_code_1 = require("../../api-handlers/onboarding/send-email-code");
+Object.defineProperty(exports, "POST", { enumerable: true, get: function () { return send_email_code_1.POST; } });

package/dist/routes/onboarding/set-password.d.ts

@@ -0,0 +1,2 @@
+/** POST /api/onboarding/set-password -> IdP (PAY-2121). */
+export { POST } from '../../api-handlers/onboarding/set-password';

package/dist/routes/onboarding/set-password.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+/** POST /api/onboarding/set-password -> IdP (PAY-2121). */
+var set_password_1 = require("../../api-handlers/onboarding/set-password");
+Object.defineProperty(exports, "POST", { enumerable: true, get: function () { return set_password_1.POST; } });

package/dist/routes/onboarding/verify-code.d.ts

@@ -0,0 +1,2 @@
+/** POST /api/onboarding/verify-code -> IdP (PAY-2121). */
+export { POST } from '../../api-handlers/onboarding/verify-code';

package/dist/routes/onboarding/verify-code.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+/** POST /api/onboarding/verify-code -> IdP (PAY-2121). */
+var verify_code_1 = require("../../api-handlers/onboarding/verify-code");
+Object.defineProperty(exports, "POST", { enumerable: true, get: function () { return verify_code_1.POST; } });

package/dist/routes/onboarding/verify-welcome-email.d.ts

@@ -0,0 +1,2 @@
+/** POST /api/onboarding/verify-welcome-email -> IdP (PAY-2121). */
+export { POST } from '../../api-handlers/onboarding/verify-welcome-email';

package/dist/routes/onboarding/verify-welcome-email.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+/** POST /api/onboarding/verify-welcome-email -> IdP (PAY-2121). */
+var verify_welcome_email_1 = require("../../api-handlers/onboarding/verify-welcome-email");
+Object.defineProperty(exports, "POST", { enumerable: true, get: function () { return verify_welcome_email_1.POST; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.4.9",
+  "version": "4.5.0",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -575,6 +575,61 @@
       "require": "./dist/pages/verify-code/page.js",
       "default": "./dist/pages/verify-code/page.js"
     },
+    "./dist/pages/onboarding": {
+      "types": "./dist/pages/onboarding/index.d.ts",
+      "require": "./dist/pages/onboarding/index.js",
+      "default": "./dist/pages/onboarding/index.js"
+    },
+    "./pages/onboarding": {
+      "types": "./dist/pages/onboarding/index.d.ts",
+      "require": "./dist/pages/onboarding/index.js",
+      "default": "./dist/pages/onboarding/index.js"
+    },
+    "./components/auth/PasswordResetBridge": {
+      "types": "./dist/components/auth/PasswordResetBridge.d.ts",
+      "require": "./dist/components/auth/PasswordResetBridge.js",
+      "default": "./dist/components/auth/PasswordResetBridge.js"
+    },
+    "./api-handlers/onboarding/verify-code": {
+      "types": "./dist/api-handlers/onboarding/verify-code.d.ts",
+      "require": "./dist/api-handlers/onboarding/verify-code.js",
+      "default": "./dist/api-handlers/onboarding/verify-code.js"
+    },
+    "./api-handlers/onboarding/send-email-code": {
+      "types": "./dist/api-handlers/onboarding/send-email-code.d.ts",
+      "require": "./dist/api-handlers/onboarding/send-email-code.js",
+      "default": "./dist/api-handlers/onboarding/send-email-code.js"
+    },
+    "./api-handlers/onboarding/verify-welcome-email": {
+      "types": "./dist/api-handlers/onboarding/verify-welcome-email.d.ts",
+      "require": "./dist/api-handlers/onboarding/verify-welcome-email.js",
+      "default": "./dist/api-handlers/onboarding/verify-welcome-email.js"
+    },
+    "./api-handlers/onboarding/set-password": {
+      "types": "./dist/api-handlers/onboarding/set-password.d.ts",
+      "require": "./dist/api-handlers/onboarding/set-password.js",
+      "default": "./dist/api-handlers/onboarding/set-password.js"
+    },
+    "./routes/onboarding/verify-code": {
+      "types": "./dist/routes/onboarding/verify-code.d.ts",
+      "require": "./dist/routes/onboarding/verify-code.js",
+      "default": "./dist/routes/onboarding/verify-code.js"
+    },
+    "./routes/onboarding/send-email-code": {
+      "types": "./dist/routes/onboarding/send-email-code.d.ts",
+      "require": "./dist/routes/onboarding/send-email-code.js",
+      "default": "./dist/routes/onboarding/send-email-code.js"
+    },
+    "./routes/onboarding/verify-welcome-email": {
+      "types": "./dist/routes/onboarding/verify-welcome-email.d.ts",
+      "require": "./dist/routes/onboarding/verify-welcome-email.js",
+      "default": "./dist/routes/onboarding/verify-welcome-email.js"
+    },
+    "./routes/onboarding/set-password": {
+      "types": "./dist/routes/onboarding/set-password.d.ts",
+      "require": "./dist/routes/onboarding/set-password.js",
+      "default": "./dist/routes/onboarding/set-password.js"
+    },
     "./pages/admin-login": {
       "types": "./dist/pages/admin-login/page.d.ts",
       "require": "./dist/pages/admin-login/page.js",

package/src/api-handlers/onboarding/send-email-code.ts

@@ -0,0 +1,18 @@
+/**
+ * POST /api/onboarding/send-email-code (PAY-2121).
+ *
+ * Body: { onboard_token } - token-driven, no session. Thin proxy to the IdP's
+ * POST /api/Onboarding/send-email-code. The IdP derives the recipient from the
+ * token's BOUND email only, never from client input, so a tampered link cannot
+ * redirect the code. Also the resend leg the verify card's cooldown fires
+ * against.
+ */
+import { NextRequest } from 'next/server';
+import { onboardingBadRequest, onboardingProxy } from '../../lib/onboarding-proxy';
+
+export async function POST(req: NextRequest) {
+  const body = await req.json().catch(() => ({} as Record<string, unknown>));
+  const onboardToken = (body as Record<string, unknown>)?.onboard_token;
+  if (!onboardToken) return onboardingBadRequest('MISSING_TOKEN', 'onboard_token is required');
+  return onboardingProxy(req, '/api/Onboarding/send-email-code');
+}

package/src/api-handlers/onboarding/set-password.ts

@@ -0,0 +1,21 @@
+/**
+ * POST /api/onboarding/set-password (PAY-2121).
+ *
+ * Body: { onboard_token, email, reset_token, new_password } - the locked
+ * contract (IdP OnboardingDtos.cs SetPasswordRequest, all four snake_case).
+ * email + reset_token come from the verify-code response; the IdP re-checks
+ * email against the token's bound user before consuming the single-use token.
+ * On success the IdP sets the password AND completes onboarding (issues tokens).
+ * Thin proxy - status and body pass through verbatim.
+ */
+import { NextRequest } from 'next/server';
+import { onboardingBadRequest, onboardingProxy } from '../../lib/onboarding-proxy';
+
+export async function POST(req: NextRequest) {
+  const body = await req.json().catch(() => ({} as Record<string, unknown>));
+  const b = body as Record<string, unknown>;
+  if (!b?.onboard_token) return onboardingBadRequest('MISSING_TOKEN', 'onboard_token is required');
+  if (!b?.email || !b?.reset_token) return onboardingBadRequest('MISSING_RESET_CONTEXT', 'email and reset_token (from verify-code) are required');
+  if (!b?.new_password) return onboardingBadRequest('MISSING_PASSWORD', 'new_password is required');
+  return onboardingProxy(req, '/api/Onboarding/set-password');
+}

package/src/api-handlers/onboarding/verify-code.ts

@@ -0,0 +1,20 @@
+/**
+ * POST /api/onboarding/verify-code (PAY-2121).
+ *
+ * Body: { onboard_token, code } - token-driven, no session. Thin proxy to the
+ * IdP's POST /api/Onboarding/verify-code, which answers
+ * { success, reset_token, email, client_key } on success (OnboardingDtos.cs
+ * VerifyCodeResponse). reset_token + email are what the set-password step needs
+ * next. The onboard_token IS the auth; there is no session to attach.
+ */
+import { NextRequest } from 'next/server';
+import { onboardingBadRequest, onboardingProxy } from '../../lib/onboarding-proxy';
+
+export async function POST(req: NextRequest) {
+  const body = await req.json().catch(() => ({} as Record<string, unknown>));
+  const onboardToken = (body as Record<string, unknown>)?.onboard_token;
+  const code = (body as Record<string, unknown>)?.code;
+  if (!onboardToken) return onboardingBadRequest('MISSING_TOKEN', 'onboard_token is required');
+  if (!code) return onboardingBadRequest('MISSING_CODE', 'code is required');
+  return onboardingProxy(req, '/api/Onboarding/verify-code');
+}

package/src/api-handlers/onboarding/verify-welcome-email.ts

@@ -0,0 +1,17 @@
+/**
+ * POST /api/onboarding/verify-welcome-email (PAY-2121).
+ *
+ * Body: { onboard_token } - token-driven, no session. Thin proxy to the IdP's
+ * POST /api/Onboarding/verify-welcome-email, which answers the masked contact
+ * info + expiry the verify card displays. The onboarding page calls this to
+ * render its "check your email / here is what we know" state.
+ */
+import { NextRequest } from 'next/server';
+import { onboardingBadRequest, onboardingProxy } from '../../lib/onboarding-proxy';
+
+export async function POST(req: NextRequest) {
+  const body = await req.json().catch(() => ({} as Record<string, unknown>));
+  const onboardToken = (body as Record<string, unknown>)?.onboard_token;
+  if (!onboardToken) return onboardingBadRequest('MISSING_TOKEN', 'onboard_token is required');
+  return onboardingProxy(req, '/api/Onboarding/verify-welcome-email');
+}

package/src/auth/password-reset-bridge.ts

@@ -0,0 +1,98 @@
+/**
+ * PAY-2121: the fragment bridge on `/`.
+ *
+ * The IdP's post-verify redirect for a passwordless account lands on
+ *   ORIGIN/#password_reset_required=true&reset_token=<token>&email=<addr>
+ * - a FRAGMENT, never a query (ProgressiveAuthController.cs:1204-1222). A fresh
+ * @payez/next-mvp app has no fragment handling at all, so the user lands on `/`
+ * and nothing happens; their reset is lost.
+ *
+ * This is the PURE half (data in, data out) so a test can execute it without a
+ * DOM. The client component (PasswordResetBridge) calls it on mount with
+ * `window.location.hash`. The kit's reset surface is the existing
+ * `/account-auth/recovery` page, which reads `?email=` and a reset token - so the
+ * bridge rewrites the fragment into that surface's OWN query shape and navigates
+ * once. It invents no new reset flow.
+ *
+ * CONTRACT:
+ *   '#password_reset_required=true&reset_token=T&email=a%40b.co' -> '/account-auth/recovery?token=T&email=a%40b.co'
+ *   any other fragment (no flag, flag != true, no token) -> null (leave `/` alone)
+ */
+
+/** The reset surface the bridge hands off to, by its existing path. */
+export const RECOVERY_PATH = '/account-auth/recovery';
+
+/**
+ * PAY-2121 (BAPert 70576): the recovery page's ENTRY decision, as a pure function.
+ *
+ * The bridge now sends a VERIFIED passwordless user to
+ *   /account-auth/recovery?token=<reset_token>&email=<addr>
+ * with a REAL reset token in hand. If the page then showed its request-a-code
+ * step, it would throw that token away and the flow would still dead-end - just
+ * one page later. So when a token is present the page must start at the
+ * set-password step and submit straight through resetPasswordWithToken.
+ *
+ *   token present      -> { step: 'set-password', resetToken: <token> }
+ *   no token           -> { step: 'initiate',    resetToken: null }   (today's behaviour)
+ */
+export function recoveryEntry(
+  token: string | null | undefined,
+  email: string | null | undefined,
+): { step: 'set-password' | 'initiate'; resetToken: string | null; email: string } {
+  const tok = (token ?? '').trim();
+  return {
+    step: tok ? 'set-password' : 'initiate',
+    resetToken: tok || null,
+    email: (email ?? '').trim(),
+  };
+}
+
+/**
+ * PAY-2121 (BAPert 70582): the set-password SUBMIT precondition, as a pure
+ * function. The old guard was `if (!passwordResetToken || !recoverySession) return;`.
+ * Removing the session half (so a deep-linked reset can submit) must NOT let a
+ * submit with NO token reach the API carrying an empty token - which is exactly
+ * what a guard-less submit would do. This decides it, in one testable place:
+ *
+ *   resetSubmitTarget(resetToken, sessionEmail, queryEmail):
+ *     - no token (after trim)          -> null   (REFUSE: never call the API with an empty token)
+ *     - token, session email present   -> { token, email: sessionEmail }
+ *     - token, only a query email      -> { token, email: queryEmail }  (the deep-link case)
+ *     - token, but NO email anywhere    -> null   (REFUSE: nothing to reset)
+ *
+ * Returns the exact { token, email } the caller must pass to
+ * accountApi.resetPasswordWithToken, or null to refuse BEFORE any request.
+ */
+export function resetSubmitTarget(
+  resetToken: string | null | undefined,
+  sessionEmail: string | null | undefined,
+  queryEmail: string | null | undefined,
+): { token: string; email: string } | null {
+  const tok = (resetToken ?? '').trim();
+  if (!tok) return null;
+  const email = ((sessionEmail ?? '').trim() || (queryEmail ?? '').trim());
+  if (!email) return null;
+  return { token: tok, email };
+}
+
+/**
+ * The redirect the fragment asks for, or null when the fragment is not a reset
+ * request. `hash` is `window.location.hash` (leading '#' optional).
+ *
+ * Returns null - leaves `/` untouched - when:
+ *   - the fragment is empty;
+ *   - `password_reset_required` is absent or not exactly 'true';
+ *   - no `reset_token` is present (nothing to reset with; not a real link).
+ */
+export function passwordResetRedirect(hash: string | null | undefined): string | null {
+  const raw = (hash ?? '').replace(/^#/, '');
+  if (!raw) return null;
+  const params = new URLSearchParams(raw);
+  if (params.get('password_reset_required') !== 'true') return null;
+  const token = params.get('reset_token') ?? '';
+  if (!token) return null;
+  const email = params.get('email') ?? '';
+  const qs = new URLSearchParams({ token });
+  if (email) qs.set('email', email);
+  return `${RECOVERY_PATH}?${qs.toString()}`;
+}

package/src/auth/route-config.ts

@@ -63,6 +63,23 @@ const defaultUnauthenticatedRoutes: UnauthenticatedRouteConfig[] = [
     allowDuringCircuitBreakerOpen: true,
     requiresRateLimit: false
   },
+  // PAY-2121: the IdP emails an invite link to /account-auth/onboarding and a
+  // post-verify reset FRAGMENT on '/'. Both must be reachable unauthenticated -
+  // the invitee has no session (the onboard_token IS the credential), and the
+  // fragment lands on the already-public root. Listed explicitly, not left to
+  // the /account-auth/* wildcard, so the two conventional paths are visible here.
+  {
+    pattern: '/account-auth/onboarding',
+    description: 'IdP invite/onboarding landing page (token-driven, no session)',
+    allowDuringCircuitBreakerOpen: true,
+    requiresRateLimit: false
+  },
+  {
+    pattern: '/api/onboarding/*',
+    description: 'Onboarding API (token-driven, no session)',
+    allowDuringCircuitBreakerOpen: true,
+    requiresRateLimit: true
+  },
   {
     pattern: '/api/auth/*',
     description: 'Authentication API endpoints',

package/src/components/auth/PasswordResetBridge.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import { useEffect } from 'react';
+import { passwordResetRedirect } from '../../auth/password-reset-bridge';
+
+/**
+ * PAY-2121: mount this once on your app's `/` page. When the IdP's post-verify
+ * redirect lands on `/#password_reset_required=true&reset_token=<t>&email=<e>`
+ * (a FRAGMENT), this performs ONE replace to the kit's reset surface and clears
+ * the hash. With any other fragment it renders nothing and leaves `/` alone.
+ *
+ * It renders nothing and reads no user data - it only inspects the fragment.
+ *
+ * @example
+ * // app/page.tsx
+ * import { PasswordResetBridge } from '@payez/next-mvp/components/auth/PasswordResetBridge';
+ * export default function Home() {
+ *   return (&lt;&gt;&lt;PasswordResetBridge /&gt;&lt;/&gt;);
+ * }
+ */
+export function PasswordResetBridge() {
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const target = passwordResetRedirect(window.location.hash);
+    if (target) window.location.replace(target);
+  }, []);
+  return null;
+}
+
+export default PasswordResetBridge;