@payez/next-mvp 4.8.6 → 4.8.8

package/README.md

@@ -548,7 +548,7 @@ import { POST as logout } from '@payez/next-mvp/routes/auth/logout';
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `CLIENT_ID` | ✅ Yes | Your PayEz IDP client ID (string slug, e.g., `payez_idp_admin_web`) |
-| `IDP_URL` | ✅ Yes | PayEz IDP base URL (e.g., `https://idp.payez.net` or `http://localhost:32785`) |
+| `IDP_URL` | ✅ Yes | PayEz IDP base URL (e.g., `https://idp.payez.net` or `http://localhost:32785`). **No default in code.** Call `requireIdpUrl()` from `@payez/next-mvp/lib/require-idp-url` in your `instrumentation.ts` (4.8.8) and the server refuses to start, with one fixed sentence, when it is missing or not a full http(s) address. The quickstart generator writes the production address into `.env.local` and adds that file for you. |
 | `AUTH_TRUST_HOST` | ✅ Yes | Must be `true` - NextAuth derives OAuth URLs from request headers |
 | `NEXTAUTH_SECRET` | 🔄 Broker | **Do NOT set** - fetched automatically from IDP at startup (see below) |
 | `CLIENT_SECRET` | ⚠️ Legacy | Not needed with broker mode - IDP handles signing |

package/dist/api-handlers/onboarding/send-email-code.js

@@ -7,5 +7,5 @@ async function POST(req) {
     const onboardToken = body?.onboard_token;
     if (!onboardToken)
         return (0, onboarding_proxy_1.onboardingBadRequest)('MISSING_TOKEN', 'onboard_token is required');
-    return (0, onboarding_proxy_1.onboardingProxy)(req, '/api/Onboarding/send-email-code');
+    return (0, onboarding_proxy_1.onboardingProxy)(req, '/api/Onboarding/send-email-code', body);
 }

package/dist/api-handlers/onboarding/set-password.js

@@ -11,5 +11,5 @@ async function POST(req) {
         return (0, onboarding_proxy_1.onboardingBadRequest)('MISSING_RESET_CONTEXT', 'email and reset_token (from verify-code) are required');
     if (!b?.new_password)
         return (0, onboarding_proxy_1.onboardingBadRequest)('MISSING_PASSWORD', 'new_password is required');
-    return (0, onboarding_proxy_1.onboardingProxy)(req, '/api/Onboarding/set-password');
+    return (0, onboarding_proxy_1.onboardingProxy)(req, '/api/Onboarding/set-password', body);
 }

package/dist/api-handlers/onboarding/verify-code.js

@@ -10,5 +10,5 @@ async function POST(req) {
         return (0, onboarding_proxy_1.onboardingBadRequest)('MISSING_TOKEN', 'onboard_token is required');
     if (!code)
         return (0, onboarding_proxy_1.onboardingBadRequest)('MISSING_CODE', 'code is required');
-    return (0, onboarding_proxy_1.onboardingProxy)(req, '/api/Onboarding/verify-code');
+    return (0, onboarding_proxy_1.onboardingProxy)(req, '/api/Onboarding/verify-code', body);
 }

package/dist/api-handlers/onboarding/verify-welcome-email.js

@@ -7,5 +7,5 @@ async function POST(req) {
     const onboardToken = body?.onboard_token;
     if (!onboardToken)
         return (0, onboarding_proxy_1.onboardingBadRequest)('MISSING_TOKEN', 'onboard_token is required');
-    return (0, onboarding_proxy_1.onboardingProxy)(req, '/api/Onboarding/verify-welcome-email');
+    return (0, onboarding_proxy_1.onboardingProxy)(req, '/api/Onboarding/verify-welcome-email', body);
 }

package/dist/lib/onboarding-code-client.d.ts

@@ -8,3 +8,10 @@ export type OnboardingCodeResult = {
     devCode: string | null;
 };
 export declare function requestOnboardingCode(onboardToken: string, fetchImpl?: typeof fetch): Promise<OnboardingCodeResult>;
+/** Where the code step stands: the page has asked the IdP to email a code ('sending'), the IdP said yes ('sent') or no ('failed'). */
+export type CodeState = 'sending' | 'sent' | 'failed';
+/**
+ * 4.8.7 (QAPert 75864): the code step used to say "We emailed you a 6-digit code" before anything was sent, and kept saying it when
+ * the send failed. It now says a code was emailed ONLY when the IdP answered ok.
+ */
+export declare function codeStepSentence(state: CodeState, maskedEmail: string | null): string;

package/dist/lib/onboarding-code-client.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.requestOnboardingCode = requestOnboardingCode;
+exports.codeStepSentence = codeStepSentence;
 function pick(j) {
     const o = j;
     return o?.dev_verification_code ?? o?.data?.dev_verification_code ?? o?.data?.result?.dev_verification_code ?? o?.result?.dev_verification_code;
@@ -20,3 +21,15 @@ async function requestOnboardingCode(onboardToken, fetchImpl = fetch) {
         return { ok: false, devCode: null };
     }
 }
+/**
+ * 4.8.7 (QAPert 75864): the code step used to say "We emailed you a 6-digit code" before anything was sent, and kept saying it when
+ * the send failed. It now says a code was emailed ONLY when the IdP answered ok.
+ */
+function codeStepSentence(state, maskedEmail) {
+    if (state === 'sent') {
+        return maskedEmail ? `We emailed a 6-digit code to ${maskedEmail}. Enter it below.` : 'We emailed you a 6-digit code. Enter it below.';
+    }
+    if (state === 'sending')
+        return 'Sending you a 6-digit code…';
+    return 'We could not send a code. Choose "Send a new code" to try again.';
+}

package/dist/lib/onboarding-proxy.d.ts

@@ -21,10 +21,10 @@ export declare function onboardingBadRequest(code: string, message: string): Nex
     };
 }>;
 /**
- * POST a JSON body to `{IDP_URL}{idpPath}` with no credentials, and relay the
+ * POST `body` (the handler's ALREADY-PARSED JSON) 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 declare function onboardingProxy(req: NextRequest, idpPath: string): Promise<NextResponse>;
+export declare function onboardingProxy(req: NextRequest, idpPath: string, body: unknown): Promise<NextResponse>;

package/dist/lib/onboarding-proxy.js

@@ -23,26 +23,28 @@ function onboardingBadRequest(code, message) {
     return server_1.NextResponse.json({ success: false, message, error: { code } }, { status: 400 });
 }
 /**
- * POST a JSON body to `{IDP_URL}{idpPath}` with no credentials, and relay the
+ * POST `body` (the handler's ALREADY-PARSED JSON) 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.
  */
-async function onboardingProxy(req, idpPath) {
+async function onboardingProxy(req, idpPath, body) {
     const idpBase = env_1.ENV_CONFIG.IDP_URL;
     if (!idpBase) {
         return server_1.NextResponse.json({ success: false, message: 'IDP_URL is not configured', error: { code: 'NO_IDP_URL' } }, { status: 500 });
     }
     const url = `${idpBase}${idpPath}`;
     (0, idp_url_guard_1.assertAbsoluteIdpUrl)(url);
-    let bodyText = '{}';
-    try {
-        const raw = await req.text();
-        if (raw && raw.trim().length > 0)
-            bodyText = raw;
+    // 4.8.7: the handler has ALREADY read the request body to check its fields, and a Request body is single-read. The proxy used to
+    // call req.text() again, which threw "Body has already been read", swallowed it, and POSTed '{}' to the IdP: every onboarding
+    // step from a generated app (4.5.0 - 4.8.6) reached Core with no token. The parsed body is passed in; the request is only read
+    // for its forwarding headers.
+    // A caller that did not pass the parsed body is a bug in this package, and it must be LOUD: it used to become '{}' at the IdP.
+    if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+        return server_1.NextResponse.json({ success: false, message: 'The onboarding request body was not forwarded.', error: { code: 'BODY_NOT_FORWARDED' } }, { status: 500 });
     }
-    catch { /* empty body is fine */ }
+    const bodyText = JSON.stringify(body);
     const headers = { 'Content-Type': 'application/json', Accept: 'application/json' };
     const xfwd = req.headers.get('x-forwarded-for') || req.headers.get('x-real-ip');
     if (xfwd)

package/dist/lib/require-idp-url.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 4.8.8 (item 24, Jon: "fast and loud are how i like my config errors"): the app REQUIRES IDP_URL and says so at START.
+ *
+ * There is no default in code. The quickstart generator writes the production sign-in service address into the app's .env.local
+ * at generation time; rigs override that file. When the value is missing, empty or not an absolute http(s) address, the server
+ * refuses to come up - printed once, in one fixed sentence, exit code 1 - instead of booting and failing on the first sign-in.
+ *
+ * A leaf module: no imports, so a generated `instrumentation.ts` can load it without pulling the session store or the logger.
+ */
+export declare const IDP_URL_REQUIRED_SENTENCE = "IDP_URL is not set to a full http(s) address. This app has no default sign-in service: set IDP_URL in .env.local and start again.";
+/** True when IDP_URL is present and absolute. Otherwise logs the fixed sentence and calls `exit(1)`; returns false if `exit` returns. */
+export declare function requireIdpUrl(env?: Record<string, string | undefined>, exit?: (code: number) => unknown, log?: (line: string) => void): boolean;

package/dist/lib/require-idp-url.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDP_URL_REQUIRED_SENTENCE = void 0;
+exports.requireIdpUrl = requireIdpUrl;
+/**
+ * 4.8.8 (item 24, Jon: "fast and loud are how i like my config errors"): the app REQUIRES IDP_URL and says so at START.
+ *
+ * There is no default in code. The quickstart generator writes the production sign-in service address into the app's .env.local
+ * at generation time; rigs override that file. When the value is missing, empty or not an absolute http(s) address, the server
+ * refuses to come up - printed once, in one fixed sentence, exit code 1 - instead of booting and failing on the first sign-in.
+ *
+ * A leaf module: no imports, so a generated `instrumentation.ts` can load it without pulling the session store or the logger.
+ */
+exports.IDP_URL_REQUIRED_SENTENCE = 'IDP_URL is not set to a full http(s) address. This app has no default sign-in service: set IDP_URL in .env.local and start again.';
+/** True when IDP_URL is present and absolute. Otherwise logs the fixed sentence and calls `exit(1)`; returns false if `exit` returns. */
+function requireIdpUrl(env = process.env, exit = (code) => process.exit(code), log = (line) => console.error(line)) {
+    const value = (env.IDP_URL ?? '').trim();
+    if (/^https?:\/\/[^/\s]+/i.test(value))
+        return true;
+    log('');
+    log('[STARTUP FAILED - REFUSING TO SERVE]');
+    log(`  ${exports.IDP_URL_REQUIRED_SENTENCE}`);
+    log('');
+    exit(1);
+    return false;
+}

package/dist/pages/onboarding/page.js

@@ -21,21 +21,21 @@ function OnboardingContent() {
     const [busy, setBusy] = (0, react_1.useState)(false);
     const [error, setError] = (0, react_1.useState)(null);
     const [devCode, setDevCode] = (0, react_1.useState)(null);
-    const [codeNote, setCodeNote] = (0, react_1.useState)(null);
+    const [codeState, setCodeState] = (0, react_1.useState)('sending');
     const sentFor = (0, react_1.useRef)(null);
     // 4.8.6: the page asks for the code itself, once per token (nothing else ever sends it). The dev echo, if the IdP gave one in
     // this answer, is shown under the code box; nothing else can make it appear.
     async function sendCode() {
-        setCodeNote(null);
+        setCodeState('sending');
         const r = await (0, onboarding_code_client_1.requestOnboardingCode)(onboardToken);
         setDevCode(r.devCode);
-        setCodeNote(r.ok ? 'A new code was sent.' : 'We could not send a code. Try again in a moment.');
+        setCodeState(r.ok ? 'sent' : 'failed');
     }
     (0, react_1.useEffect)(() => {
         if (!onboardToken || sentFor.current === onboardToken)
             return;
         sentFor.current = onboardToken;
-        void (0, onboarding_code_client_1.requestOnboardingCode)(onboardToken).then((r) => setDevCode(r.devCode));
+        void (0, onboarding_code_client_1.requestOnboardingCode)(onboardToken).then((r) => { setDevCode(r.devCode); setCodeState(r.ok ? 'sent' : 'failed'); });
     }, [onboardToken]);
     // 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.
@@ -114,9 +114,7 @@ function OnboardingContent() {
             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.`
-                            : 'We emailed you a 6-digit code. Enter it below.' }), (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' })] }), (0, jsx_runtime_1.jsx)(DevCodeNotice_1.DevCodeNotice, { code: devCode }), (0, jsx_runtime_1.jsxs)("p", { style: { marginTop: 12, fontSize: 13 }, children: [(0, jsx_runtime_1.jsx)("button", { type: "button", onClick: () => void sendCode(), "data-testid": "resend-code", style: { background: 'none', border: 'none', padding: 0, color: H.primary, fontWeight: 600, textDecoration: 'underline', cursor: 'pointer' }, children: "Send a new code" }), codeNote && (0, jsx_runtime_1.jsx)("span", { role: "status", style: { marginLeft: 8, color: H.secondary }, children: codeNote })] })] })), 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 })] }));
+    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: (0, onboarding_code_client_1.codeStepSentence)(codeState, maskedEmail) }), (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' })] }), (0, jsx_runtime_1.jsx)(DevCodeNotice_1.DevCodeNotice, { code: devCode }), (0, jsx_runtime_1.jsx)("p", { style: { marginTop: 12, fontSize: 13 }, children: (0, jsx_runtime_1.jsx)("button", { type: "button", onClick: () => void sendCode(), "data-testid": "resend-code", style: { background: 'none', border: 'none', padding: 0, color: H.primary, fontWeight: 600, textDecoration: 'underline', cursor: 'pointer' }, children: "Send a new code" }) })] })), 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' };

package/dist/routes/account/masked-info.d.ts

@@ -22,7 +22,7 @@ export { POST } from '../../api-handlers/account/masked-info';
  * email/phone options to the user.
  *
  * Environment variables used:
- * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
+ * - IDP_URL or NEXT_PUBLIC_IDP_URL (REQUIRED: there is no default in code)
  * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
  * - BETTER_AUTH_SECRET (required — fetched from IDP at startup)
  *

package/dist/routes/account/masked-info.js

@@ -28,7 +28,7 @@ Object.defineProperty(exports, "POST", { enumerable: true, get: function () { re
  * email/phone options to the user.
  *
  * Environment variables used:
- * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
+ * - IDP_URL or NEXT_PUBLIC_IDP_URL (REQUIRED: there is no default in code)
  * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
  * - BETTER_AUTH_SECRET (required — fetched from IDP at startup)
  *

package/dist/routes/account/send-code.d.ts

@@ -26,7 +26,7 @@ export { POST } from '../../api-handlers/account/send-code';
  * - contactId: string - ID of the masked contact to send to
  *
  * Environment variables used:
- * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
+ * - IDP_URL or NEXT_PUBLIC_IDP_URL (REQUIRED: there is no default in code)
  * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
  * - BETTER_AUTH_SECRET (required — fetched from IDP at startup)
  *

package/dist/routes/account/send-code.js

@@ -31,7 +31,7 @@ Object.defineProperty(exports, "POST", { enumerable: true, get: function () { re
  * - contactId: string - ID of the masked contact to send to
  *
  * Environment variables used:
- * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
+ * - IDP_URL or NEXT_PUBLIC_IDP_URL (REQUIRED: there is no default in code)
  * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
  * - BETTER_AUTH_SECRET (required — fetched from IDP at startup)
  *

package/dist/routes/account/verify-email.d.ts

@@ -25,7 +25,7 @@ export { POST } from '../../api-handlers/account/verify-email';
  * - emailId: string - ID of the email address used
  *
  * Environment variables used:
- * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
+ * - IDP_URL or NEXT_PUBLIC_IDP_URL (REQUIRED: there is no default in code)
  * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
  * - BETTER_AUTH_SECRET (required — fetched from IDP at startup)
  *

package/dist/routes/account/verify-email.js

@@ -30,7 +30,7 @@ Object.defineProperty(exports, "POST", { enumerable: true, get: function () { re
  * - emailId: string - ID of the email address used
  *
  * Environment variables used:
- * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
+ * - IDP_URL or NEXT_PUBLIC_IDP_URL (REQUIRED: there is no default in code)
  * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
  * - BETTER_AUTH_SECRET (required — fetched from IDP at startup)
  *

package/dist/routes/account/verify-sms.d.ts

@@ -25,7 +25,7 @@ export { POST } from '../../api-handlers/account/verify-sms';
  * - phoneId: string - ID of the phone number used
  *
  * Environment variables used:
- * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
+ * - IDP_URL or NEXT_PUBLIC_IDP_URL (REQUIRED: there is no default in code)
  * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
  * - BETTER_AUTH_SECRET (required — fetched from IDP at startup)
  *

package/dist/routes/account/verify-sms.js

@@ -30,7 +30,7 @@ Object.defineProperty(exports, "POST", { enumerable: true, get: function () { re
  * - phoneId: string - ID of the phone number used
  *
  * Environment variables used:
- * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
+ * - IDP_URL or NEXT_PUBLIC_IDP_URL (REQUIRED: there is no default in code)
  * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
  * - BETTER_AUTH_SECRET (required — fetched from IDP at startup)
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.8.6",
+  "version": "4.8.8",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,6 @@
     "prepack": "npm run build && npm run check:publish-eol",
     "prepublishOnly": "npm run check:publish-eol && npm run build",
     "postpublish": "node scripts/check-publish-health.mjs",
-    "postversion": "node scripts/check-publish-health.mjs || echo \"[postversion] see above: local/registry are out of sync after this version bump (171900)\"",
     "dev": "next dev",
     "dev:local": "pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/dev-local.ps1",
     "dev:broker": "pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/dev-broker.ps1",
@@ -180,6 +179,11 @@
       "require": "./dist/lib/api-handler.js",
       "default": "./dist/lib/api-handler.js"
     },
+    "./lib/require-idp-url": {
+      "types": "./dist/lib/require-idp-url.d.ts",
+      "require": "./dist/lib/require-idp-url.js",
+      "default": "./dist/lib/require-idp-url.js"
+    },
     "./lib/startup-init": {
       "types": "./dist/lib/startup-init.d.ts",
       "require": "./dist/lib/startup-init.js",

package/scripts/check-publish-health.mjs

@@ -21,10 +21,14 @@
  *   - Missing auth is reported as its OWN outcome, not folded into "lagging".
  *     Those are different failures with different fixes (credential vs publish).
  *
+ * MEANINGFUL ONLY IN THE TREE THAT PUBLISHED: another checkout or dist packs a different integrity (CRLF vs LF, a different build).
  * Usage:  node scripts/check-publish-health.mjs
- * Exit:   0 = registry is at or ahead of local
- *         1 = registry LAGS local (unpublished versions exist)
+ * Exit:   0 = the dist-tag points at the local version AND the registry's integrity for it equals the packed tarball's
+ *         1 = it does not (timeout with the two values it last saw, an integrity mismatch, never published, no auth)
  *         2 = could not determine (network/registry/parse) — inconclusive, NOT a pass
+ * Flag:   --timeout-ms <n> (0 = one read, no waiting; `postversion` uses it because nothing is published yet at that point).
+ * Env:    PUBLISH_HEALTH_TIMEOUT_MS (default 600000): how long to wait for the registry to reflect the publish. Measured stale
+ *         for about 5-7 minutes after every publish 4.8.3 - 4.8.6, so a short bound fails a good publish. (BAPert 75831)
  */
 
 import { execFileSync } from 'node:child_process';
@@ -32,6 +36,7 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { resolvePublishTag } from './publish-health-tag.mjs';
+import { pollRegistry, resolveTimeoutMs } from './publish-health-poll.mjs';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const pkgPath = join(here, '..', 'package.json');
@@ -44,21 +49,6 @@ function run(args) {
   }).trim();
 }
 
-function sleepSync(ms) {
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-
-/** Numeric-aware semver compare. Returns >0 if a > b, 0 if equal, <0 if a < b. */
-function compareVersions(a, b) {
-  const norm = (v) => String(v).split('-')[0].split('.').map((n) => parseInt(n, 10) || 0);
-  const [x, y] = [norm(a), norm(b)];
-  for (let i = 0; i < Math.max(x.length, y.length); i++) {
-    const d = (x[i] ?? 0) - (y[i] ?? 0);
-    if (d !== 0) return d;
-  }
-  return 0;
-}
-
 let local;
 try {
   local = JSON.parse(readFileSync(pkgPath, 'utf8'));
@@ -101,62 +91,77 @@ try {
 // which is the dangerous action — and against a registry that refuses republication
 // it burns a version number, which is how a version string ends up naming two trees.
 //
-// `--prefer-online` forces revalidation. The bounded retry covers real propagation
-// delay, which is seconds, not weeks.
+// `--prefer-online` forces revalidation, and the bounded poll (publish-health-poll.mjs) covers the propagation delay: measured
+// 5-7 MINUTES of stale reads after each publish 4.8.3 - 4.8.6, which is why the default bound is 10 minutes, not seconds.
 //
-// THIS DOES NOT SOFTEN THE CHECK, and it must not be "helpfully" turned into a warning:
-// a genuine lag (the 171900 failure mode — a dead credential leaving versions
-// unpublished for WEEKS) still exhausts every attempt and still exits non-zero. The
-// retry changes how accurately we read the registry, never what counts as a failure.
-const REGISTRY_ATTEMPTS = 4;
-const REGISTRY_RETRY_MS = 2000;
+// THIS DOES NOT SOFTEN THE CHECK, and it must not be "helpfully" turned into a warning: it passes only when the tag points at
+// the version we published AND the registry's integrity for it equals the tarball we packed. A genuine lag (the 171900 failure
+// mode — a dead credential leaving versions unpublished for WEEKS) exhausts the poll and still exits 1, printing what it saw.
+const TIMEOUT_MS = resolveTimeoutMs(process.argv.slice(2), process.env);
+if (TIMEOUT_MS === null) {
+  console.error('[publish-health] INCONCLUSIVE: --timeout-ms / PUBLISH_HEALTH_TIMEOUT_MS must be a non-negative integer (milliseconds).');
+  process.exit(2);
+}
+
+// The integrity of the tarball WE packed: `npm pack --dry-run --json` reports it without writing a file, and --ignore-scripts keeps
+// it from re-running prepack/build. Measured 2026-10-20: from a clean LF tree at the published commit it reproduced 4.8.6's
+// registry integrity exactly. If it cannot be computed the check is INCONCLUSIVE, never a pass.
+let packIntegrity;
+try {
+  const out = JSON.parse(run(['pack', '--dry-run', '--json', '--ignore-scripts']));
+  packIntegrity = Array.isArray(out) ? out[0]?.integrity : out?.integrity;
+  if (typeof packIntegrity !== 'string' || !packIntegrity) throw new Error('npm pack reported no integrity');
+} catch (err) {
+  console.error(`[publish-health] INCONCLUSIVE: cannot compute the packed tarball's integrity: ${String(err.message).split('\n')[0]}`);
+  process.exit(2);
+}
 
-let registryVersion = null;
-for (let attempt = 1; attempt <= REGISTRY_ATTEMPTS; attempt++) {
+const is404 = (err) => /E404|404 Not Found/.test(String(err.stderr || err.message || ''));
+const view = (spec, field) => {
   try {
-    registryVersion = run(['view', registrySpec, 'version', '--prefer-online']);
+    return run(['view', spec, field, '--prefer-online']) || null;
   } catch (err) {
-    const msg = String(err.stderr || err.message || '');
-    if (/E404|404 Not Found/.test(msg)) {
-      console.error(`[publish-health] FAIL: ${registrySpec} has NEVER been published to the registry.`);
-      console.error(`[publish-health] local=${localVersion} registry=<absent>`);
-      process.exit(1);
-    }
-    console.error(`[publish-health] INCONCLUSIVE: could not query the registry: ${msg.split('\n')[0]}`);
-    console.error('[publish-health] Treat as UNKNOWN, not as a pass.');
-    process.exit(2);
-  }
-
-  // Stop as soon as the registry is at or ahead of local. Only an apparent lag is
-  // worth re-reading, and only because THIS script's own hook makes a stale read likely.
-  if (compareVersions(localVersion, registryVersion) <= 0) break;
-
-  if (attempt < REGISTRY_ATTEMPTS) {
-    console.log(
-      `[publish-health] registry says ${registryVersion}, local is ${localVersion} — ` +
-      `re-reading (${attempt}/${REGISTRY_ATTEMPTS - 1}) in case this is post-publish propagation lag.`,
-    );
-    sleepSync(REGISTRY_RETRY_MS);
+    if (is404(err)) return null;
+    throw new Error(`could not query the registry for ${spec}: ${String(err.stderr || err.message || '').split('\n')[0]}`);
   }
-}
-
-const delta = compareVersions(localVersion, registryVersion);
+};
+
+console.log(`[publish-health] waiting up to ${Math.round(TIMEOUT_MS / 1000)}s for ${registrySpec} to show ${localVersion} with the packed integrity`);
+const r = await pollRegistry({
+  readTag: () => view(registrySpec, 'version'),
+  readIntegrity: () => view(`${name}@${localVersion}`, 'dist.integrity'),
+  localVersion,
+  packIntegrity,
+  timeoutMs: TIMEOUT_MS,
+  sleep: (ms) => new Promise((res) => setTimeout(res, ms)),
+  onWait: (w) => console.log(`[publish-health] not yet (attempt ${w.attempts}): tag ${tag} -> ${w.sawTag ?? '<absent>'}, integrity ${w.sawIntegrity ?? '<not visible>'}; re-reading in ${Math.round(w.nextDelayMs / 1000)}s`),
+});
 
 console.log(`[publish-health] package  : ${name}`);
-console.log(`[publish-health] local    : ${localVersion}`);
-console.log(`[publish-health] registry : ${registryVersion} (dist-tag ${tag})`);
+console.log(`[publish-health] local    : ${localVersion}  packed integrity ${packIntegrity}`);
+console.log(`[publish-health] registry : dist-tag ${tag} -> ${r.sawTag ?? '<absent>'}, integrity ${r.sawIntegrity ?? '<not visible>'}`);
 console.log(`[publish-health] npm auth : ${authUser ? `logged in as ${authUser}` : 'NOT AUTHENTICATED (npm whoami failed)'}`);
 
-if (delta > 0) {
+if (r.reason === 'unreadable') {
+  console.error(`[publish-health] INCONCLUSIVE: the registry could not be read: ${r.lastError}`);
+  console.error('[publish-health] Treat as UNKNOWN, not as a pass.');
+  process.exit(2);
+}
+if (!r.ok) {
   console.error('');
-  console.error(`[publish-health] FAIL: the registry LAGS local by at least one version.`);
-  console.error(`[publish-health] ${localVersion} is built locally but the registry serves ${registryVersion}.`);
+  if (r.reason === 'integrity-mismatch') {
+    console.error(`[publish-health] FAIL: the registry's ${localVersion} is NOT the tarball packed here.`);
+    console.error('[publish-health] If this is not the tree that published, the mismatch is expected: re-run there before concluding anything.');
+  } else {
+    console.error(`[publish-health] FAIL: after ${Math.round(TIMEOUT_MS / 1000)}s the registry does not show ${localVersion} under ${tag} with the packed integrity.`);
+  }
+  console.error(`[publish-health] saw: dist-tag ${tag} -> ${r.sawTag ?? '<absent>'}; integrity of ${localVersion} -> ${r.sawIntegrity ?? '<not visible>'}`);
+  console.error(`[publish-health] want: dist-tag ${tag} -> ${localVersion}; integrity ${packIntegrity}`);
   if (!authUser) {
     console.error('[publish-health] ROOT CAUSE LIKELY: npm is not authenticated on this machine.');
     console.error('[publish-health] This is the 171900 failure mode — a silent credential expiry.');
   }
-  console.error('[publish-health] Unpublished versions are invisible to every consumer that is not');
-  console.error('[publish-health] installing from a local tarball. See cards 171900 / 185177.');
+  console.error('[publish-health] Do NOT publish again to "fix" this: check the registry by hand first (a second publish of the same version is refused).');
   process.exit(1);
 }
 
@@ -167,5 +172,5 @@ if (!authUser) {
   process.exit(1);
 }
 
-console.log('[publish-health] OK: registry is at or ahead of local, and auth is live.');
+console.log('[publish-health] OK: the dist-tag points at the published version, the integrity matches the packed tarball, and auth is live.');
 process.exit(0);

package/scripts/publish-health-poll.mjs

@@ -0,0 +1,83 @@
+/**
+ * The decision half of the postpublish health check (BAPert 75831): after `npm publish`, poll the registry until BOTH
+ *   (1) the dist-tag we published under points at exactly the version we published, AND
+ *   (2) that version's dist.integrity equals the integrity of the tarball we packed,
+ * and pass only on that equality. Pure and injectable (readers, sleep, clock) so the rows can run it against a stubbed registry.
+ *
+ * WHY POLL, AND FOR HOW LONG. Right after a successful publish the registry's own reads are stale for minutes (measured on every
+ * publish 4.8.3 - 4.8.6: "version not found" for about 5-7 minutes). A single read, or a handful of 2-second retries, fails a
+ * publish that is fine, and a check that always fails is a check that gets overridden by habit. The poll is bounded and it never
+ * softens: on timeout or mismatch the result is NOT ok and carries the two values it last saw.
+ *
+ * A read of the exact version's integrity that comes back DIFFERENT from the pack's is final (a published version is immutable),
+ * so it fails immediately instead of waiting out the clock.
+ *
+ * Readers: readTag() -> the version the tag points at, or null if the tag/package is absent. readIntegrity() -> the published
+ * integrity of the local version, or null if that version is not visible yet. A reader that throws is an unreadable registry.
+ */
+export const DEFAULTS = { timeoutMs: 10 * 60 * 1000, firstDelayMs: 5000, maxDelayMs: 30000, factor: 1.5 };
+
+export async function pollRegistry({
+  readTag,
+  readIntegrity,
+  localVersion,
+  packIntegrity,
+  timeoutMs = DEFAULTS.timeoutMs,
+  firstDelayMs = DEFAULTS.firstDelayMs,
+  maxDelayMs = DEFAULTS.maxDelayMs,
+  factor = DEFAULTS.factor,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  now = () => Date.now(),
+  onWait = () => {},
+}) {
+  const started = now();
+  let delay = firstDelayMs;
+  let attempts = 0;
+  let sawTag = null;
+  let sawIntegrity = null;
+  let lastError = null;
+  let reads = 0;
+  for (;;) {
+    attempts += 1;
+    try {
+      sawTag = await readTag();
+      sawIntegrity = await readIntegrity();
+      lastError = null;
+      reads += 1;
+    } catch (err) {
+      lastError = String((err && err.message) || err);
+    }
+    if (!lastError) {
+      if (sawIntegrity !== null && sawIntegrity !== packIntegrity) {
+        return { ok: false, reason: 'integrity-mismatch', attempts, sawTag, sawIntegrity };
+      }
+      if (sawTag === localVersion && sawIntegrity === packIntegrity) {
+        return { ok: true, reason: 'match', attempts, sawTag, sawIntegrity };
+      }
+    }
+    if (now() - started + delay > timeoutMs) {
+      return { ok: false, reason: reads === 0 ? 'unreadable' : 'timeout', attempts, sawTag, sawIntegrity, lastError };
+    }
+    onWait({ attempts, sawTag, sawIntegrity, lastError, nextDelayMs: delay });
+    await sleep(delay);
+    delay = Math.min(Math.round(delay * factor), maxDelayMs);
+  }
+}
+
+/**
+ * How long to wait: `--timeout-ms <n>` / `--timeout-ms=<n>` (a flag, because an env prefix does not work in Windows cmd), then
+ * PUBLISH_HEALTH_TIMEOUT_MS, then the default. 0 is a real value (one read, no waiting): `postversion` runs BEFORE anything is
+ * published, so the new version cannot be on the registry yet and waiting would only delay `npm version` (NightHawk, PR 1386).
+ * A value that is not a non-negative integer returns null - the caller treats it as inconclusive, never as the default.
+ */
+export function resolveTimeoutMs(argv = [], env = {}) {
+  let raw;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--timeout-ms') { raw = argv[i + 1]; break; }
+    if (a.startsWith('--timeout-ms=')) { raw = a.slice('--timeout-ms='.length); break; }
+  }
+  if (raw === undefined) raw = env.PUBLISH_HEALTH_TIMEOUT_MS;
+  if (raw === undefined || raw === '') return DEFAULTS.timeoutMs;
+  return /^\d+$/.test(String(raw)) ? Number.parseInt(raw, 10) : null;
+}

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

@@ -14,5 +14,5 @@ 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');
+  return onboardingProxy(req, '/api/Onboarding/send-email-code', body);
 }

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

@@ -17,5 +17,5 @@ export async function POST(req: NextRequest) {
   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');
+  return onboardingProxy(req, '/api/Onboarding/set-password', body);
 }

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

@@ -16,5 +16,5 @@ export async function POST(req: NextRequest) {
   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');
+  return onboardingProxy(req, '/api/Onboarding/verify-code', body);
 }

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

@@ -13,5 +13,5 @@ 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');
+  return onboardingProxy(req, '/api/Onboarding/verify-welcome-email', body);
 }

package/src/lib/onboarding-code-client.ts

@@ -29,3 +29,18 @@ export async function requestOnboardingCode(
     return { ok: false, devCode: null };
   }
 }
+
+/** Where the code step stands: the page has asked the IdP to email a code ('sending'), the IdP said yes ('sent') or no ('failed'). */
+export type CodeState = 'sending' | 'sent' | 'failed';
+
+/**
+ * 4.8.7 (QAPert 75864): the code step used to say "We emailed you a 6-digit code" before anything was sent, and kept saying it when
+ * the send failed. It now says a code was emailed ONLY when the IdP answered ok.
+ */
+export function codeStepSentence(state: CodeState, maskedEmail: string | null): string {
+  if (state === 'sent') {
+    return maskedEmail ? `We emailed a 6-digit code to ${maskedEmail}. Enter it below.` : 'We emailed you a 6-digit code. Enter it below.';
+  }
+  if (state === 'sending') return 'Sending you a 6-digit code…';
+  return 'We could not send a code. Choose "Send a new code" to try again.';
+}

package/src/lib/onboarding-proxy.ts

@@ -21,24 +21,31 @@ export function onboardingBadRequest(code: string, message: string) {
 }
 
 /**
- * POST a JSON body to `{IDP_URL}{idpPath}` with no credentials, and relay the
+ * POST `body` (the handler's ALREADY-PARSED JSON) 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> {
+export async function onboardingProxy(req: NextRequest, idpPath: string, body: unknown): 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 */ }
+  // 4.8.7: the handler has ALREADY read the request body to check its fields, and a Request body is single-read. The proxy used to
+  // call req.text() again, which threw "Body has already been read", swallowed it, and POSTed '{}' to the IdP: every onboarding
+  // step from a generated app (4.5.0 - 4.8.6) reached Core with no token. The parsed body is passed in; the request is only read
+  // for its forwarding headers.
+  // A caller that did not pass the parsed body is a bug in this package, and it must be LOUD: it used to become '{}' at the IdP.
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+    return NextResponse.json(
+      { success: false, message: 'The onboarding request body was not forwarded.', error: { code: 'BODY_NOT_FORWARDED' } },
+      { status: 500 },
+    );
+  }
+  const bodyText = JSON.stringify(body);
 
   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');

package/src/lib/require-idp-url.ts

@@ -0,0 +1,27 @@
+/**
+ * 4.8.8 (item 24, Jon: "fast and loud are how i like my config errors"): the app REQUIRES IDP_URL and says so at START.
+ *
+ * There is no default in code. The quickstart generator writes the production sign-in service address into the app's .env.local
+ * at generation time; rigs override that file. When the value is missing, empty or not an absolute http(s) address, the server
+ * refuses to come up - printed once, in one fixed sentence, exit code 1 - instead of booting and failing on the first sign-in.
+ *
+ * A leaf module: no imports, so a generated `instrumentation.ts` can load it without pulling the session store or the logger.
+ */
+export const IDP_URL_REQUIRED_SENTENCE =
+  'IDP_URL is not set to a full http(s) address. This app has no default sign-in service: set IDP_URL in .env.local and start again.';
+
+/** True when IDP_URL is present and absolute. Otherwise logs the fixed sentence and calls `exit(1)`; returns false if `exit` returns. */
+export function requireIdpUrl(
+  env: Record<string, string | undefined> = process.env,
+  exit: (code: number) => unknown = (code) => process.exit(code),
+  log: (line: string) => void = (line) => console.error(line),
+): boolean {
+  const value = (env.IDP_URL ?? '').trim();
+  if (/^https?:\/\/[^/\s]+/i.test(value)) return true;
+  log('');
+  log('[STARTUP FAILED - REFUSING TO SERVE]');
+  log(`  ${IDP_URL_REQUIRED_SENTENCE}`);
+  log('');
+  exit(1);
+  return false;
+}

package/src/pages/onboarding/page.tsx

@@ -3,7 +3,7 @@
 import React, { Suspense, useEffect, useRef, useState } from 'react';
 import { useSearchParams } from 'next/navigation';
 import { DevCodeNotice } from '../../components/auth/DevCodeNotice';
-import { requestOnboardingCode } from '../../lib/onboarding-code-client';
+import { requestOnboardingCode, codeStepSentence, type CodeState } from '../../lib/onboarding-code-client';
 
 /**
  * PAY-2121: the /account-auth/onboarding landing page.
@@ -47,21 +47,21 @@ function OnboardingContent() {
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [devCode, setDevCode] = useState<string | null>(null);
-  const [codeNote, setCodeNote] = useState<string | null>(null);
+  const [codeState, setCodeState] = useState<CodeState>('sending');
   const sentFor = useRef<string | null>(null);
 
   // 4.8.6: the page asks for the code itself, once per token (nothing else ever sends it). The dev echo, if the IdP gave one in
   // this answer, is shown under the code box; nothing else can make it appear.
   async function sendCode() {
-    setCodeNote(null);
+    setCodeState('sending');
     const r = await requestOnboardingCode(onboardToken);
     setDevCode(r.devCode);
-    setCodeNote(r.ok ? 'A new code was sent.' : 'We could not send a code. Try again in a moment.');
+    setCodeState(r.ok ? 'sent' : 'failed');
   }
   useEffect(() => {
     if (!onboardToken || sentFor.current === onboardToken) return;
     sentFor.current = onboardToken;
-    void requestOnboardingCode(onboardToken).then((r) => setDevCode(r.devCode));
+    void requestOnboardingCode(onboardToken).then((r) => { setDevCode(r.devCode); setCodeState(r.ok ? 'sent' : 'failed'); });
   }, [onboardToken]);
 
   // Step 1: tell the invitee which address the code went to (masked). Best
@@ -150,9 +150,7 @@ function OnboardingContent() {
         <>
           <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.`
-              : 'We emailed you a 6-digit code. Enter it below.'}
+            {codeStepSentence(codeState, maskedEmail)}
           </p>
           <form onSubmit={submitCode} noValidate style={{ marginTop: 16 }}>
             <input
@@ -173,7 +171,6 @@ function OnboardingContent() {
             <button type="button" onClick={() => void sendCode()} data-testid="resend-code" style={{ background: 'none', border: 'none', padding: 0, color: H.primary, fontWeight: 600, textDecoration: 'underline', cursor: 'pointer' }}>
               Send a new code
             </button>
-            {codeNote && <span role="status" style={{ marginLeft: 8, color: H.secondary }}>{codeNote}</span>}
           </p>
         </>
       )}

package/src/routes/account/masked-info.ts

@@ -26,7 +26,7 @@ export { POST } from '../../api-handlers/account/masked-info';
  * email/phone options to the user.
  *
  * Environment variables used:
- * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
+ * - IDP_URL or NEXT_PUBLIC_IDP_URL (REQUIRED: there is no default in code)
  * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
  * - BETTER_AUTH_SECRET (required — fetched from IDP at startup)
  *

package/src/routes/account/send-code.ts

@@ -29,7 +29,7 @@ export { POST } from '../../api-handlers/account/send-code';
  * - contactId: string - ID of the masked contact to send to
  *
  * Environment variables used:
- * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
+ * - IDP_URL or NEXT_PUBLIC_IDP_URL (REQUIRED: there is no default in code)
  * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
  * - BETTER_AUTH_SECRET (required — fetched from IDP at startup)
  *

package/src/routes/account/verify-email.ts

@@ -28,7 +28,7 @@ export { POST } from '../../api-handlers/account/verify-email';
  * - emailId: string - ID of the email address used
  *
  * Environment variables used:
- * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
+ * - IDP_URL or NEXT_PUBLIC_IDP_URL (REQUIRED: there is no default in code)
  * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
  * - BETTER_AUTH_SECRET (required — fetched from IDP at startup)
  *

package/src/routes/account/verify-sms.ts

@@ -28,7 +28,7 @@ export { POST } from '../../api-handlers/account/verify-sms';
  * - phoneId: string - ID of the phone number used
  *
  * Environment variables used:
- * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
+ * - IDP_URL or NEXT_PUBLIC_IDP_URL (REQUIRED: there is no default in code)
  * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
  * - BETTER_AUTH_SECRET (required — fetched from IDP at startup)
  *