@payez/next-mvp 4.4.9 → 4.5.0

package/src/lib/onboarding-proxy.ts

@@ -0,0 +1,57 @@
+/**
+ * PAY-2121: shared anonymous IDP proxy for the /api/onboarding/* handlers.
+ *
+ * The onboarding flow is TOKEN-DRIVEN: the invitee has no account or session
+ * yet, and the onboard_token IS the credential. So these calls must NOT go
+ * through idpFetchJSON (which injects a Bearer from a Redis session) - there is
+ * no session. They are plain server-to-server POSTs to the IdP, exactly as the
+ * VibeID portal's hand-built /api/onboarding/* routes do (card 182611).
+ *
+ * WHY A SERVER ROUTE AT ALL, AND NOT A BROWSER CALL: the IdP URL is not exposed
+ * to the browser, and the route is the one place that owns that. The token is
+ * forwarded, never the IdP's host.
+ */
+import { NextRequest, NextResponse } from 'next/server';
+import { ENV_CONFIG } from '../config/env';
+import { assertAbsoluteIdpUrl } from './idp-url-guard';
+
+/** A typed refusal in the kit's error envelope - used for a missing field, BEFORE any IdP call. */
+export function onboardingBadRequest(code: string, message: string) {
+  return NextResponse.json({ success: false, message, error: { code } }, { status: 400 });
+}
+
+/**
+ * POST a JSON body to `{IDP_URL}{idpPath}` with no credentials, and relay the
+ * IdP's status and body verbatim (the page acts on what the IdP actually
+ * returns, not on a shape this layer guesses). Never relays the IdP error TEXT
+ * for a non-2xx is NOT done here: the onboarding endpoints answer structured
+ * envelopes the page reads; the page owns the copy.
+ */
+export async function onboardingProxy(req: NextRequest, idpPath: string): Promise<NextResponse> {
+  const idpBase = ENV_CONFIG.IDP_URL;
+  if (!idpBase) {
+    return NextResponse.json({ success: false, message: 'IDP_URL is not configured', error: { code: 'NO_IDP_URL' } }, { status: 500 });
+  }
+  const url = `${idpBase}${idpPath}`;
+  assertAbsoluteIdpUrl(url);
+  let bodyText = '{}';
+  try {
+    const raw = await req.text();
+    if (raw && raw.trim().length > 0) bodyText = raw;
+  } catch { /* empty body is fine */ }
+
+  const headers: Record<string, string> = { 'Content-Type': 'application/json', Accept: 'application/json' };
+  const xfwd = req.headers.get('x-forwarded-for') || req.headers.get('x-real-ip');
+  if (xfwd) headers['X-Forwarded-For'] = xfwd;
+  const ua = req.headers.get('user-agent');
+  if (ua) headers['User-Agent'] = ua;
+
+  let res: Response;
+  try {
+    res = await fetch(url, { method: 'POST', headers, body: bodyText, cache: 'no-store' });
+  } catch {
+    return NextResponse.json({ success: false, message: 'The identity service is unreachable.', error: { code: 'UPSTREAM_UNREACHABLE' } }, { status: 502 });
+  }
+  const json = await res.json().catch(() => null);
+  return NextResponse.json(json ?? { success: res.ok }, { status: res.status });
+}

package/src/pages/login/page.tsx

@@ -311,13 +311,10 @@ function LoginForm({ altAuthSlot }: { altAuthSlot?: React.ReactNode }) {
           </div>
         </div>
 
-        {/* Additional Info */}
-        <p className={`mt-4 text-center text-sm ${colors.muted}`}>
-          Don't have an account?{' '}
-          <a href="/account-auth/register" className="themed-link font-medium hover:underline">
-            Sign up
-          </a>
-        </p>
+        {/* PAY-2121: the kit ships no sign-up PAGE (registration is the owner-initiated
+            invite/onboarding flow, not a self-serve screen), so the old "Sign up" link to
+            the register path was a dead end - it 404'd at the developer's site. Removed;
+            the README says how registration is reached. */}
       </div>
     </div>
     </>

package/src/pages/onboarding/index.ts

@@ -0,0 +1,11 @@
+/**
+ * PAY-2121: the onboarding surface.
+ *
+ *   default     - the /account-auth/onboarding page (mount from the scaffold at
+ *                 app/account-auth/onboarding/page.tsx).
+ *   PasswordResetBridge - mount once on `/` to honour the IdP's post-verify
+ *                 `#password_reset_required=true` fragment.
+ */
+export { default } from './page';
+export { default as OnboardingPage } from './page';
+export { PasswordResetBridge } from '../../components/auth/PasswordResetBridge';

package/src/pages/onboarding/page.tsx

@@ -0,0 +1,212 @@
+'use client';
+
+import React, { Suspense, useEffect, useState } from 'react';
+import { useSearchParams } from 'next/navigation';
+
+/**
+ * PAY-2121: the /account-auth/onboarding landing page.
+ *
+ * The IdP's welcome/invite email links to
+ *   {site}/account-auth/onboarding?client_id=<numeric>&onboard_token=<token>
+ * (OnboardingLinkService.BuildOnboardingLink, PayEz-Core). A fresh
+ * @payez/next-mvp app had NO page at that path, so the invitee 404'd at the
+ * developer's own site. This page mounts it.
+ *
+ * It is TOKEN-DRIVEN: the invitee has no account or session; the onboard_token
+ * IS the credential. The page forwards { onboard_token } to the kit's onboarding
+ * API (the /api/onboarding/* handlers), which proxy the IdP. Two steps:
+ *   1. verify-welcome-email -> the masked contact info the invitee recognises;
+ *   2. verify-code -> reset_token + email; then set-password -> onboarding done.
+ *
+ * MOUNTING (what README section 5 asks a consumer to write; the CLI scaffold
+ * writes it too):
+ *   app/account-auth/onboarding/page.tsx:
+ *     export { default } from '@payez/next-mvp/pages/onboarding';
+ *
+ * A missing onboard_token is a typed state, never a crash: it renders a plain
+ * "this link is missing its token" with a way back to sign-in.
+ */
+
+type Step = 'code' | 'password' | 'done';
+
+const H = { primary: 'var(--text-primary)', secondary: 'var(--text-secondary)', muted: 'var(--text-muted)' } as const;
+
+function OnboardingContent() {
+  const params = useSearchParams();
+  const onboardToken = params?.get('onboard_token') ?? '';
+
+  const [step, setStep] = useState<Step>('code');
+  const [maskedEmail, setMaskedEmail] = useState<string | null>(null);
+  const [digits, setDigits] = useState('');
+  const [password, setPassword] = useState('');
+  const [confirm, setConfirm] = useState('');
+  const [resetToken, setResetToken] = useState('');
+  const [email, setEmail] = useState('');
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(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.
+  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 (
+      <Shell>
+        <h1 style={titleStyle}>This invitation link is missing its token.</h1>
+        <p style={{ color: H.secondary, fontSize: 14, marginTop: 8 }}>
+          The link may have been truncated or copied incompletely. Ask for a new invitation, or sign in if you already have an
+          account.
+        </p>
+        <p style={{ marginTop: 16 }}>
+          <a href="/account-auth/login" style={linkStyle}>Go to sign in</a>
+        </p>
+      </Shell>
+    );
+  }
+
+  async function submitCode(e: React.FormEvent) {
+    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: React.FormEvent) {
+    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 (
+    <Shell>
+      {step === 'code' && (
+        <>
+          <h1 style={titleStyle}>Finish setting up your account</h1>
+          <p style={{ color: H.secondary, fontSize: 14, marginTop: 8 }}>
+            {maskedEmail
+              ? `We emailed a 6-digit code to ${maskedEmail}. Enter it below.`
+              : 'Enter the 6-digit code from your invitation email.'}
+          </p>
+          <form onSubmit={submitCode} noValidate style={{ marginTop: 16 }}>
+            <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 }}
+            />
+            <button type="submit" disabled={busy || digits.length < 6} style={ctaStyle(busy || digits.length < 6)}>
+              {busy ? 'Verifying…' : 'Verify'}
+            </button>
+          </form>
+        </>
+      )}
+
+      {step === 'password' && (
+        <>
+          <h1 style={titleStyle}>Choose a password</h1>
+          <p style={{ color: H.secondary, fontSize: 14, marginTop: 8 }}>Set the password you will sign in with.</p>
+          <form onSubmit={submitPassword} noValidate style={{ marginTop: 16 }}>
+            <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} aria-label="New password" placeholder="New password" style={inputStyle} />
+            <input type="password" value={confirm} onChange={(e) => setConfirm(e.target.value)} aria-label="Confirm password" placeholder="Confirm password" style={{ ...inputStyle, marginTop: 10 }} />
+            <button type="submit" disabled={busy || !password || !confirm} style={ctaStyle(busy || !password || !confirm)}>
+              {busy ? 'Saving…' : 'Set password'}
+            </button>
+          </form>
+        </>
+      )}
+
+      {step === 'done' && (
+        <>
+          <h1 style={titleStyle}>You&apos;re all set.</h1>
+          <p style={{ color: H.secondary, fontSize: 14, marginTop: 8 }}>Your account is ready. You can sign in now.</p>
+          <p style={{ marginTop: 16 }}>
+            <a href="/account-auth/login" style={linkStyle}>Go to sign in</a>
+          </p>
+        </>
+      )}
+
+      {error && <p style={{ color: '#b00020', fontSize: 13, marginTop: 12 }}>{error}</p>}
+    </Shell>
+  );
+}
+
+const titleStyle: React.CSSProperties = { color: H.primary, fontSize: 20, fontWeight: 600, margin: 0 };
+const linkStyle: React.CSSProperties = { color: H.primary, fontWeight: 600, textDecoration: 'underline' };
+const inputStyle: React.CSSProperties = {
+  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: boolean): React.CSSProperties => ({
+  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 }: { children: React.ReactNode }) {
+  return (
+    <div style={{ minHeight: '100vh', display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 16, background: 'var(--bg-default, #f9fafb)' }}>
+      <div style={{ width: '100%', maxWidth: 420, background: 'var(--bg-card, #fff)', border: '1px solid var(--border-default, #e5e7eb)', borderRadius: 16, padding: 28 }}>
+        {children}
+      </div>
+    </div>
+  );
+}
+
+export default function OnboardingPage() {
+  return (
+    <Suspense fallback={<div style={{ minHeight: '100vh' }} />}>
+      <OnboardingContent />
+    </Suspense>
+  );
+}

package/src/pages/recovery/page.tsx

@@ -4,6 +4,7 @@ import { useState, useEffect, Suspense } from 'react';
 import { useRouter, useSearchParams } from 'next/navigation';
 import { RecoveryStep, RecoverySession, PasswordResetToken } from '../../types/recovery';
 import { accountApi } from '../../utils/api';
+import { recoveryEntry, resetSubmitTarget } from '../../auth/password-reset-bridge';
 import { InitiateRecoveryStep } from '../../components/recovery/InitiateRecoveryStep';
 import { SelectMethodStep } from '../../components/recovery/SelectMethodStep';
 import { VerifyCodeStep } from '../../components/recovery/VerifyCodeStep';
@@ -15,15 +16,21 @@ import { useColors } from '../../theme/useTheme';
 function RecoveryContent() {
   const router = useRouter();
   const searchParams = 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 = recoveryEntry(searchParams?.get('token'), searchParams?.get('email'));
   const colors = useColors();
 
-  const [currentStep, setCurrentStep] = useState<RecoveryStep>('initiate');
-  const [email, setEmail] = useState(prefilledEmail);
+  const [currentStep, setCurrentStep] = useState<RecoveryStep>(entry.step);
+  const [email, setEmail] = useState(entry.email);
   const [recoverySession, setRecoverySession] = useState<RecoverySession | null>(null);
   const [selectedMethod, setSelectedMethod] = useState<'email' | 'sms' | 'authenticator' | null>(null);
   const [verificationCode, setVerificationCode] = useState('');
-  const [passwordResetToken, setPasswordResetToken] = useState<PasswordResetToken | null>(null);
+  const [passwordResetToken, setPasswordResetToken] = useState<PasswordResetToken | null>(
+    entry.resetToken ? { token: entry.resetToken, expiresAt: '' } : null,
+  );
   const [error, setError] = useState<string | null>(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] = useState(false);
@@ -113,7 +120,14 @@ function RecoveryContent() {
   };
 
   const handleResetPassword = async (password: string, confirmPassword: string) => {
-    if (!passwordResetToken || !recoverySession) return;
+    // 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 = 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);
@@ -121,8 +135,8 @@ function RecoveryContent() {
 
     try {
       const response = await accountApi.resetPasswordWithToken(
-        recoverySession.email,
-        passwordResetToken.token,
+        target.email,
+        target.token,
         password,
         confirmPassword
       );
@@ -144,7 +158,9 @@ function RecoveryContent() {
   const handleGoBack = () => {
     if (currentStep === 'select-method') setCurrentStep('initiate');
     else if (currentStep === 'verify-code') setCurrentStep('select-method');
-    else if (currentStep === 'set-password') setCurrentStep('verify-code');
+    // 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(recoverySession ? 'verify-code' : 'initiate');
   };
 
   return (

package/src/routes/onboarding/index.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/src/routes/onboarding/send-email-code.ts

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

package/src/routes/onboarding/set-password.ts

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

package/src/routes/onboarding/verify-code.ts

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

package/src/routes/onboarding/verify-welcome-email.ts

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