@payez/next-mvp 4.5.7 → 4.7.9

package/src/components/auth/CredentialSignInForm.tsx

@@ -0,0 +1,240 @@
+'use client';
+
+import React, { useState } from 'react';
+import { TraditionalAuthSection } from './TraditionalAuthSection';
+import { safeCallbackPath } from '../../auth/safe-callback';
+import { authorizeResumeHref } from '../../lib/authorize-resume';
+import { NO_CODE_REQUEST, codeStepInstruction, type CodeRequest } from '../../lib/code-step-copy';
+import {
+  credentialSignIn,
+  requestEmailCode,
+  validateCredentials,
+  type FetchLike,
+} from '../../lib/credential-sign-in-client';
+
+/**
+ * PAY-2302 cut 1b: the package's email + password (+ 2FA code) sign-in form.
+ *
+ * WHY IT EXISTS. The package's own Better Auth instance has no emailAndPassword, so the login page had no credential form
+ * (removed 2026-08-02, BAPert 17586: "restore this form together" with the backend that makes it work). This is that pair:
+ * the backend is routes/auth/credential-login (+ credential-login-email-code), which the app mounts at
+ * /api/auth/admin-login[/email-code]; this component drives it. Moved from the portal's AdminLoginCard (VibeID-Customer-Portal
+ * 3d654917), re-styled with the package's own TraditionalAuthSection instead of the portal's AuthCard chrome.
+ *
+ * MOUNT IT through the login page's slot, so nothing changes for a consumer that does not opt in:
+ *     <LoginPage altAuthSlot={<CredentialSignInForm />} />
+ * (An app that has not mounted the two routes must NOT mount this form: it would be the dead control 17586 removed.)
+ *
+ * Two steps, the IdP's own contract (an access token with no refresh token means a second factor is outstanding):
+ *   'credentials' - email + password
+ *   'code'        - the 2FA code; the door parks the provisional bearer in an httpOnly cookie, this step resubmits with the code.
+ *
+ * After success the browser goes to the callbackUrl, passed through safeCallbackPath (same-origin paths only); when the page
+ * carries ?return_url (an IdP authorize request) it goes to the app's /api/oauth/resume instead, which resumes that request.
+ */
+
+interface Props {
+  /** Where to go after sign-in. Default: the page's ?callbackUrl, else /dashboard. Always passed through safeCallbackPath. */
+  callbackUrl?: string;
+  /** Test seam: the fetch used for both doors. */
+  fetchImpl?: FetchLike;
+  /** Test seam: navigation after success. */
+  onSignedIn?: (destination: string) => void;
+  showForgotPassword?: boolean;
+}
+
+const inputStyle: React.CSSProperties = {
+  borderColor: 'var(--border-default, #e5e7eb)',
+  color: 'var(--text-primary, #111827)',
+  background: 'var(--bg-input, white)',
+};
+
+export function resolveDestination(explicit?: string): string {
+  let raw = explicit;
+  let returnUrl: string | null = null;
+  if (typeof window !== 'undefined') {
+    const params = new URLSearchParams(window.location.search);
+    if (raw === undefined) raw = params.get('callbackUrl') ?? undefined;
+    // PAY-2302 cut 2: an IdP that sent the user here mid-authorize (?return_url=<IdP authorize request>) must get the
+    // authorize request resumed after sign-in. The href points at the app's OWN /api/oauth/resume, which validates the
+    // URL against IDP_URL server-side; nothing absolute is navigated to from here, and the result is still guarded.
+    returnUrl = params.get('return_url');
+  }
+  return safeCallbackPath(authorizeResumeHref(returnUrl), safeCallbackPath(raw, '/dashboard'));
+}
+
+export function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPassword = false }: Props) {
+  const [step, setStep] = useState<'credentials' | 'code'>('credentials');
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [code, setCode] = useState('');
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [fieldError, setFieldError] = useState<string | null>(null);
+  const [codeRequest, setCodeRequest] = useState<CodeRequest>(NO_CODE_REQUEST);
+  const [offerEmailCode, setOfferEmailCode] = useState(false);
+  const [emailCodeMsg, setEmailCodeMsg] = useState<string | null>(null);
+
+  async function submit(withCode?: string) {
+    setBusy(true);
+    setError(null);
+    setOfferEmailCode(false);
+    try {
+      const r = await credentialSignIn({ email, password, code: withCode }, fetchImpl);
+      if (r.kind === 'success') {
+        const destination = resolveDestination(callbackUrl);
+        if (onSignedIn) onSignedIn(destination);
+        else window.location.href = destination;
+        return;
+      }
+      if (r.kind === 'two_factor') {
+        setCodeRequest(r.codeRequest);
+        setStep('code');
+        return;
+      }
+      setError(r.message);
+      if (r.kind === 'error') setOfferEmailCode(r.offerEmailCode);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  function onCredentialsSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    const invalid = validateCredentials(email, password);
+    if (invalid) {
+      setFieldError(invalid.email ?? invalid.password ?? null);
+      return;
+    }
+    setFieldError(null);
+    void submit();
+  }
+
+  function onCodeSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    const trimmed = code.trim();
+    if (!trimmed) {
+      setFieldError('Enter your authentication code.');
+      return;
+    }
+    setFieldError(null);
+    void submit(trimmed);
+  }
+
+  function onBack() {
+    setStep('credentials');
+    setCodeRequest(NO_CODE_REQUEST);
+    setCode('');
+    setFieldError(null);
+    setError(null);
+    setOfferEmailCode(false);
+    setEmailCodeMsg(null);
+  }
+
+  async function askForEmailCode() {
+    setBusy(true);
+    setEmailCodeMsg(null);
+    try {
+      const r = await requestEmailCode(fetchImpl);
+      if (r.kind === 'requested') {
+        setCodeRequest(r.codeRequest);
+        setError(null);
+        setOfferEmailCode(false);
+        setEmailCodeMsg('We asked for a code to be emailed to you. Enter it above when it arrives.');
+      } else {
+        setEmailCodeMsg(r.message);
+      }
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const problem = fieldError ?? error;
+  const problemLine = problem && (
+    <p role="alert" data-testid="credential-sign-in-error" className="text-sm mt-3" style={{ color: 'var(--color-error, #ef4444)' }}>
+      {problem}
+    </p>
+  );
+
+  if (step === 'code') {
+    return (
+      <div data-testid="credential-sign-in-code-step" className="text-left">
+        <p className="text-sm mb-4" style={{ color: 'var(--text-primary, #111827)' }}>{codeStepInstruction(email, codeRequest)}</p>
+        <form onSubmit={onCodeSubmit} noValidate className="space-y-4">
+          <div>
+            <label htmlFor="credential-code" className="block text-sm font-medium mb-2" style={{ color: 'var(--text-primary, #111827)' }}>
+              Authentication code
+            </label>
+            <input
+              id="credential-code"
+              name="code"
+              type="text"
+              inputMode="numeric"
+              autoComplete="one-time-code"
+              required
+              placeholder="000000"
+              value={code}
+              disabled={busy}
+              onChange={(e) => {
+                setCode(e.target.value);
+                setFieldError(null);
+              }}
+              className="w-full px-4 py-3 rounded-lg border transition-colors focus:outline-none focus:ring-2 disabled:opacity-50"
+              style={inputStyle}
+            />
+          </div>
+          <button
+            type="submit"
+            disabled={busy}
+            className="w-full py-3 px-4 rounded-lg font-semibold focus:outline-none focus:ring-2 disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
+            style={{ background: 'var(--btn-primary-bg, #11B588)', color: 'var(--btn-primary-text, white)' }}
+          >
+            {busy ? 'Verifying…' : 'Verify'}
+          </button>
+        </form>
+        <button type="button" onClick={onBack} disabled={busy} className="text-sm underline mt-4" style={{ background: 'none', border: 'none', padding: 0, color: 'var(--text-muted, #6b7280)' }}>
+          Back
+        </button>
+        {problemLine}
+        {(offerEmailCode || emailCodeMsg) && (
+          <div data-testid="email-code-offer" className="mt-4">
+            {offerEmailCode && (
+              <button type="button" onClick={() => void askForEmailCode()} disabled={busy} className="text-sm font-semibold underline" style={{ background: 'none', border: 'none', padding: 0, color: 'var(--text-primary, #111827)' }}>
+                Email me a code instead
+              </button>
+            )}
+            {emailCodeMsg && (
+              <p role="status" data-testid="email-code-offer-msg" className="text-sm mt-2" style={{ color: 'var(--text-primary, #111827)' }}>
+                {emailCodeMsg}
+              </p>
+            )}
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <div data-testid="credential-sign-in" className="text-left">
+      <TraditionalAuthSection
+        email={email}
+        password={password}
+        onEmailChange={(v) => {
+          setEmail(v);
+          setFieldError(null);
+        }}
+        onPasswordChange={(v) => {
+          setPassword(v);
+          setFieldError(null);
+        }}
+        onSubmit={onCredentialsSubmit}
+        isLoading={busy}
+        buttonText="Sign in"
+        showForgotPassword={showForgotPassword}
+      />
+      {problemLine}
+    </div>
+  );
+}
+
+export default CredentialSignInForm;

package/src/lib/authorize-resume.ts

@@ -0,0 +1,187 @@
+/**
+ * PAY-2302 cut 2: moved VERBATIM (logic unchanged) from VibeID-Customer-Portal src/lib/auth/authorize-resume.ts.
+ * PAY-1500 (portal half of PAY-1479): resume the IdP OAuth authorize request after 2FA.
+ *
+ * The IdP sends an OAuth principal who still owes 2FA to the portal's /account-auth/verify-code with
+ *   ?next_step=enroll_mfa|mfa_verify&callbackUrl=<absolute IdP authorize URL>&return_url=<same>
+ * (OAuthController.Authorize; hotfix-2 66ca7a8eb routes BOTH cases to verify-code, /account/security is gone). safeCallbackPath rightly refuses that absolute URL,
+ * so after 2FA the user used to land on the default page and sign-in never finished.
+ *
+ * This is NOT a relaxation of safeCallbackPath. The browser is sent to the portal's own
+ * /api/oauth/resume, which checks return_url SERVER-SIDE against IDP_URL (origin + the authorize path)
+ * and only then redirects. Anything else is refused. IDP_URL never reaches the client.
+ */
+export const AUTHORIZE_RESUME_ROUTE = '/api/oauth/resume';
+const AUTHORIZE_PATH = '/api/oauth/authorize';
+
+/** True only for `<IDP_URL origin>/api/oauth/authorize` (path case-insensitive, as ASP.NET routes). */
+export function isIdpAuthorizeUrl(candidate: string | null | undefined, idpBaseUrl: string): boolean {
+  if (typeof candidate !== 'string' || candidate === '') return false;
+  try {
+    const u = new URL(candidate);
+    const idp = new URL(idpBaseUrl);
+    return (u.protocol === 'https:' || u.protocol === 'http:') && u.origin === idp.origin && u.pathname.toLowerCase() === AUTHORIZE_PATH;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Server side: the redirect target, REBUILT from trusted parts - IDP_URL's origin and the authorize path
+ * are ours; only the query string comes from the request. Null unless isIdpAuthorizeUrl holds.
+ */
+export function idpAuthorizeRedirect(candidate: string | null | undefined, idpBaseUrl: string): string | null {
+  if (!isIdpAuthorizeUrl(candidate, idpBaseUrl)) return null;
+  const query = new URL(candidate as string).search;
+  return `${new URL(idpBaseUrl).origin}/api/OAuth/authorize${query}`;
+}
+
+/**
+ * Client side: the SAME-ORIGIN portal path that resumes authorize, or null when the IdP did not ask for one.
+ * Callers still pass the result through safeCallbackPath before navigating.
+ *
+ * WHY THE ASTERISK IS RE-ENCODED (PAY-1547, measured by NextPert 59939, completeness measured here).
+ * One consumer of this value is `authClient.signIn.social({ callbackURL })`, which POSTs to better-auth
+ * and is validated by its own originCheckMiddleware BEFORE anything redirects. For a relative path that
+ * check is decided entirely by one regex (better-auth 1.5.6, auth/trusted-origins.mjs:16 - the
+ * `allowRelativePaths` branch, and api/middlewares/origin-check.mjs:51 passes
+ * `allowRelativePaths: label !== 'origin'`, so it IS that branch for a callbackURL):
+ *
+ *     /^\/(?!\/|\\|%2f|%5c)[\w\-.\+\/@]*(?:\?[\w\-.\+\/=&%@]*)?$/
+ *
+ * A character this helper emits RAW and that charset rejects is a hard 403 INVALID_CALLBACK_URL on the
+ * Google button - not a silent fallback. Measured exhaustively over printable ASCII by diffing what
+ * `URLSearchParams` leaves raw against that charset: the raw set is alphanumerics plus `* - . _`, and
+ * *** `*` IS THE ONLY REJECTED MEMBER *** (`%` is permitted, which is why every other special character
+ * survives - URLSearchParams already percent-encoded it).
+ *
+ * `*` is reachable because `state` and `scope` are chosen by the OAuth CLIENT, not by us, so we cannot
+ * decline to emit it. `%2A` is the same character to every parser: re-reading this query string returns
+ * the byte-identical `return_url` (asserted in test/authorize-resume.test.cjs), so this is an encoding
+ * change and NOT a value change. It is applied here, at the ONE computation, rather than at the sinks -
+ * the two `window.location.href` sinks are browser navigations that touch no library and for which this
+ * is a behavioural no-op, so there is no reason to make them each carry it.
+ */
+export function authorizeResumeHref(returnUrl: string | null | undefined): string | null {
+  if (typeof returnUrl !== 'string' || returnUrl === '') return null;
+  const query = new URLSearchParams({ return_url: returnUrl }).toString().replace(/\*/g, '%2A');
+  return `${AUTHORIZE_RESUME_ROUTE}?${query}`;
+}
+
+// ───────────────────────── 4.7.5 (PAY-2305): the authorize call is made SERVER-SIDE ─────────────────────────
+//
+// WHY: Core's /api/oauth/authorize identifies a user ONLY from an `Authorization: Bearer` header (JwtMiddleware reads no cookie,
+// and a browser navigation cannot send a header), so the 4.7.0-4.7.4 behaviour - 302 the BROWSER to authorize - could never
+// produce a code for anyone. The resume route now calls authorize itself with the signed-in user's IdP access token and relays
+// only the verified outcome. These helpers are the pure, testable parts.
+
+export interface ServerAuthorizeParams {
+  idpBaseUrl: string;
+  /** This app's IdP client slug (CLIENT_ID). The request's client_id must equal it. */
+  clientId: string;
+  /** The app's REGISTERED redirect_uri, e.g. http://localhost:3000/api/auth/callback. The request's redirect_uri must equal it exactly. */
+  redirectUri: string;
+}
+
+export interface ServerAuthorizeRequest {
+  /** Built from constants + validated pieces only. This is what gets fetched. */
+  url: string;
+  state: string;
+}
+
+const CHALLENGE_RE = /^[A-Za-z0-9_-]{43,128}$/;
+const STATE_RE = /^[A-Za-z0-9._~-]{1,256}$/;
+const SCOPE_RE = /^[A-Za-z0-9:._ -]{1,200}$/;
+
+/**
+ * Build the authorize URL to call, or null (refuse). Origin, path, response_type, client_id and redirect_uri are OURS; from
+ * return_url only code_challenge (+ method, S256 only), state and scope are taken, each charset/length validated. A return_url for
+ * another client or another redirect_uri is refused (no "someone else's client"). Unknown extra parameters are NOT forwarded.
+ */
+export function buildServerAuthorizeRequest(returnUrl: string | null | undefined, p: ServerAuthorizeParams): ServerAuthorizeRequest | null {
+  if (!isIdpAuthorizeUrl(returnUrl, p.idpBaseUrl) || !p.clientId || !p.redirectUri) return null;
+  const q = new URL(returnUrl as string).searchParams;
+  const once = (name: string): string | null => {
+    const all = q.getAll(name);
+    return all.length === 1 ? all[0] : all.length === 0 ? null : '\u0000'; // a repeated parameter is ambiguous: refused below
+  };
+  const responseType = once('response_type');
+  if (responseType !== null && responseType !== 'code') return null;
+  if (once('client_id') !== p.clientId) return null;
+  if (once('redirect_uri') !== p.redirectUri) return null;
+  const challenge = once('code_challenge');
+  const method = once('code_challenge_method');
+  const state = once('state');
+  const scope = once('scope');
+  if (challenge === null || !CHALLENGE_RE.test(challenge)) return null;
+  if (method !== 'S256') return null;
+  if (state === null || !STATE_RE.test(state)) return null;
+  if (scope !== null && !SCOPE_RE.test(scope)) return null;
+
+  const out = new URLSearchParams();
+  out.set('response_type', 'code');
+  out.set('client_id', p.clientId);
+  out.set('redirect_uri', p.redirectUri);
+  if (scope !== null) out.set('scope', scope);
+  out.set('state', state);
+  out.set('code_challenge', challenge);
+  out.set('code_challenge_method', 'S256');
+  return { url: `${new URL(p.idpBaseUrl).origin}${AUTHORIZE_PATH}?${out.toString()}`, state };
+}
+
+/**
+ * The IdP's answer to the server-side authorize call. Returns the RELATIVE path+query to send the browser to, or null (refuse).
+ * Only a redirect whose Location is EXACTLY the registered redirect_uri (origin + path), with a code and the state we sent and no
+ * error, qualifies. The relayed value is REBUILT from the validated code and state, never copied from the Location.
+ */
+export function relayRegisteredCallback(status: number, location: string | null | undefined, redirectUri: string, sentState: string): string | null {
+  if (status < 300 || status > 399 || typeof location !== 'string' || location === '') return null;
+  let loc: URL;
+  let reg: URL;
+  try {
+    reg = new URL(redirectUri);
+    loc = new URL(location, reg.origin);
+  } catch {
+    return null;
+  }
+  if (loc.origin !== reg.origin || loc.pathname !== reg.pathname) return null;
+  if (loc.searchParams.has('error')) return null;
+  const codes = loc.searchParams.getAll('code');
+  const states = loc.searchParams.getAll('state');
+  if (codes.length !== 1 || !/^[A-Za-z0-9._~+/=-]{8,512}$/.test(codes[0])) return null;
+  if (states.length !== 1 || states[0] !== sentState) return null;
+  return `${reg.pathname}?${new URLSearchParams({ code: codes[0], state: sentState }).toString()}`;
+}
+
+/**
+ * The resume must be a same-site navigation. Sec-Fetch-Site decides when the browser sends it; otherwise Referer must be this
+ * app's own origin; with neither it is refused (a crafted cross-site link must not make the victim's browser trigger authorize
+ * with the victim's token).
+ */
+export function isSameSiteResume(headers: { get(name: string): string | null }, appOrigin: string): boolean {
+  const sfs = headers.get('sec-fetch-site');
+  // same-origin or none only: a sibling subdomain ('same-site') is not this app.
+  if (sfs !== null) return sfs === 'same-origin' || sfs === 'none';
+  const referer = headers.get('referer');
+  if (!referer) return false;
+  try {
+    return new URL(referer).origin === appOrigin;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Binds the resume to a browser that STARTED this app's OAuth flow: better-auth (storeStateStrategy 'cookie') sets an
+ * `oauth_state` cookie (Max-Age 600; name may carry a `__Secure-` and an app prefix) when sign-in begins. Its value is sealed, so only
+ * its presence is checked; the state MATCH is enforced by better-auth's callback, which fails closed. A crafted link opened in a
+ * browser that never began the flow has no such cookie and is refused here, before the user's token is used.
+ */
+export function hasOAuthStateCookie(cookieHeader: string | null | undefined): boolean {
+  if (typeof cookieHeader !== 'string') return false;
+  return cookieHeader.split(';').some((part) => {
+    const i = part.indexOf('=');
+    const name = (i < 0 ? part : part.slice(0, i)).trim();
+    return /(^|[._-])oauth_state$/.test(name) && i >= 0 && part.slice(i + 1).trim() !== '';
+  });
+}

package/src/lib/bearer-fetch.ts

@@ -0,0 +1,31 @@
+/**
+ * PAY-1777 item 5 (QAPert-NightHawk, PR 663 G4 thread 4395; coverage widened per BAPert 64034): THE way a server-side call
+ * that carries a user's (or a provisional) bearer token talks to the identity service.
+ *
+ * A bearer must never follow a redirect. Modern fetch drops Authorization on a CROSS-origin hop, but a same-origin hop - or
+ * an older runtime - does not, and we do not rely on that. So:
+ *   - the request is always sent with redirect: 'manual' (set AFTER the caller's init, so no caller can switch it back);
+ *   - any 3xx, or an opaque redirect, is never followed and never relayed: the caller receives a synthetic
+ *     502 { success:false, error:{ code:'IDP_UNREACHABLE' } } Response instead, which every existing non-2xx branch at the
+ *     call sites already handles. Every other response is returned untouched.
+ *
+ * Moved from VibeID-Customer-Portal (src/lib/idp/bearer-fetch.ts) into the package by PAY-2302; the portal's gate
+ * (testing/qa/idp-bearer-no-redirect-gate.js) keeps inventorying its own Authorization-bearing fetches.
+ */
+export const REDIRECT_REFUSED_CODE = 'IDP_UNREACHABLE';
+
+export function isRedirectResponse(res: Response): boolean {
+  return res.type === 'opaqueredirect' || (res.status >= 300 && res.status < 400);
+}
+
+export async function bearerFetch(input: string | URL, init: RequestInit = {}): Promise<Response> {
+  const res = await fetch(input, { ...init, redirect: 'manual' });
+  if (!isRedirectResponse(res)) return res;
+  return new Response(
+    JSON.stringify({
+      success: false,
+      error: { code: REDIRECT_REFUSED_CODE, message: 'The identity service answered with a redirect; the call was not followed' },
+    }),
+    { status: 502, headers: { 'Content-Type': 'application/json' } },
+  );
+}

package/src/lib/code-step-copy.ts

@@ -0,0 +1,83 @@
+/**
+ * PAY-1576 - the 2FA "enter your code" step, described ONCE.
+ *
+ * WHY THIS FILE EXISTS. Two cards render the same step for the same door
+ * (POST /api/auth/admin-login, the package's routes/auth/credential-login, answers `requiresTwoFactor` with `sentVia` /
+ * `codeRequested` / `emailSent`):
+ *   - SignInCard.tsx      (fixed in 267479 to name every lane the box accepts)
+ *   - AdminLoginCard.tsx  (NOT fixed: it said "from your authenticator app" for every user and
+ *                          discarded the door's answer, so an email-code user was sent to a
+ *                          factor they do not have; live allowed2FAMethods=[emailcode,totp])
+ * 267479 reached only one of the twins. A comment cannot stop that recurring; a shared helper can,
+ * because there is then only one place the sentence is built and a static gate
+ * (testing/qa/code-step-copy-gate.js) fails if either card builds its own.
+ *
+ * THE COPY RULES (carried over verbatim from 267479 / 267561, not re-decided here):
+ *   - Name BOTH lanes and RANK NEITHER: the screen does not know which factor the user holds.
+ *   - The non-authenticator clause is gated on the door's answer, so we never mention a code nobody
+ *     asked for.
+ *   - `codeRequested` means "a code was requested", NOT "a code arrived" (twofa/email/send returns
+ *     200 even when the SMTP send threw), so the copy says "the code we emailed you" and never
+ *     "check your inbox" / "it has arrived".
+ */
+
+export type CodeSentVia = 'sms' | 'email' | null;
+
+export interface CodeRequest {
+  /** The door asked for a code to be sent (`codeRequested`, or the older alias `emailSent`). */
+  codeRequested: boolean;
+  /** Which lane the door actually fired, or null when nothing was sent (a TOTP holder). */
+  sentVia: CodeSentVia;
+  /**
+   * PAY-2314 (4.7.1): present and false ONLY when the door said which factors it accepts (acceptedFactors) and TOTP is not
+   * among them. Absent means "the door did not say" (an older door) and keeps the historic authenticator sentence.
+   */
+  acceptsAuthenticator?: false;
+}
+
+/** Nothing sent, nothing to say beyond the authenticator. What a card starts with. */
+export const NO_CODE_REQUEST: CodeRequest = { codeRequested: false, sentVia: null };
+
+/**
+ * Read the door's answer. Total: any shape (null, a string, an array, junk fields) yields a
+ * CodeRequest and never throws, so a malformed body degrades to the authenticator-only sentence
+ * rather than to a crash or to a claim the door never made.
+ */
+export function readCodeRequest(body: unknown): CodeRequest {
+  const b = body && typeof body === 'object' ? (body as Record<string, unknown>) : {};
+  const sentVia: CodeSentVia = b.sentVia === 'sms' || b.sentVia === 'email' ? b.sentVia : null;
+  const accepted = Array.isArray(b.acceptedFactors) ? (b.acceptedFactors as unknown[]) : null;
+  const base: CodeRequest = { codeRequested: b.codeRequested === true || b.emailSent === true, sentVia };
+  return accepted !== null && !accepted.includes('totp') ? { ...base, acceptsAuthenticator: false } : base;
+}
+
+/** The lane clause that follows the authenticator, or '' when the door sent nothing. */
+function laneClause(r: CodeRequest): string {
+  if (!r.codeRequested) return '';
+  if (r.sentVia === 'sms') return ', or the code we texted you';
+  if (r.sentVia === 'email') return ', or the code we emailed you';
+  return ', or the code we sent you';
+}
+
+/**
+ * The sentence, split around the email so a card can render the address however it likes
+ * (SignInCard wraps it in <strong>; AdminLoginCard passes a plain-string subtitle).
+ * `before + email + after` is the whole sentence.
+ */
+export function codeStepParts(r: CodeRequest): { before: string; after: string } {
+  if (r.acceptsAuthenticator === false) {
+    // PAY-2314: the door told us TOTP is not an accepted factor for this user - never send them to an authenticator they do not have.
+    const how = r.sentVia === 'sms' ? 'texted' : r.sentVia === 'email' ? 'emailed' : 'sent';
+    return { before: 'Enter your 6-digit code to finish signing in as ', after: ` — the code we ${how} you.` };
+  }
+  return {
+    before: 'Enter your 6-digit code to finish signing in as ',
+    after: ` — from your authenticator app${laneClause(r)}.`,
+  };
+}
+
+/** The sentence as one plain string, for a card whose subtitle prop is a string. */
+export function codeStepInstruction(email: string, r: CodeRequest): string {
+  const { before, after } = codeStepParts(r);
+  return `${before}${email}${after}`;
+}

package/src/lib/credential-sign-in-client.ts

@@ -0,0 +1,101 @@
+/**
+ * PAY-2302 cut 1b: the BROWSER side of the package's credential sign-in, as plain functions so it is testable without a DOM.
+ *
+ * It talks to the routes the app mounts from this package:
+ *   POST /api/auth/admin-login             routes/auth/credential-login             { email, password, code? }
+ *   POST /api/auth/admin-login/email-code  routes/auth/credential-login-email-code  (no body: the browser names no address and no client)
+ *
+ * The result is a closed union so the form cannot invent a state the door never answered. The logic mirrors the portal's
+ * AdminLoginCard.submitLogin (VibeID-Customer-Portal 3d654917) and keeps its rules:
+ *   - 429 is relayed as the door's own sentence; the form never states a window the door did not send.
+ *   - `requiresTwoFactor` moves to the code step and keeps the door's answer (sentVia / codeRequested) so the step names the
+ *     lane that was actually fired (PAY-1576).
+ *   - anything else not `success: true` is an error carrying the door's message, and `offerEmailCode` only when the door set it
+ *     literally true (PAY-2284).
+ */
+import { NO_CODE_REQUEST, readCodeRequest, type CodeRequest } from './code-step-copy';
+
+export const CREDENTIAL_LOGIN_URL = '/api/auth/admin-login';
+export const CREDENTIAL_EMAIL_CODE_URL = '/api/auth/admin-login/email-code';
+
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export type CredentialSignInResult =
+  | { kind: 'success' }
+  | { kind: 'two_factor'; codeRequest: CodeRequest }
+  | { kind: 'rate_limited'; message: string }
+  | { kind: 'error'; message: string; offerEmailCode: boolean };
+
+export const MSG_RATE_LIMITED = 'Too many attempts. Please try again later.';
+export const MSG_CANNOT_SIGN_IN = 'Could not sign in. Check your details and try again.';
+export const MSG_UNEXPECTED = 'Something went wrong signing you in. Please try again.';
+
+const EMAIL_SHAPE = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
+
+export function isEmailShaped(v: string): boolean {
+  return EMAIL_SHAPE.test(v);
+}
+
+/** Field-level checks before anything is sent. Returns the errors, or null when the input may be submitted. */
+export function validateCredentials(email: string, password: string): { email?: string; password?: string } | null {
+  const errors: { email?: string; password?: string } = {};
+  const trimmed = email.trim();
+  if (!trimmed) errors.email = 'Enter your email address.';
+  else if (!isEmailShaped(trimmed)) errors.email = 'Enter a valid email address.';
+  if (!password) errors.password = 'Enter your password.';
+  return errors.email || errors.password ? errors : null;
+}
+
+function asString(v: unknown): string | undefined {
+  return typeof v === 'string' && v ? v : undefined;
+}
+
+/** One call to the credential door. `code` is the 2FA code on the second turn; email and password are resubmitted with it. */
+export async function credentialSignIn(
+  args: { email: string; password: string; code?: string },
+  fetchImpl: FetchLike = (input, init) => fetch(input, init),
+): Promise<CredentialSignInResult> {
+  try {
+    const res = await fetchImpl(CREDENTIAL_LOGIN_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email: args.email, password: args.password, code: args.code }),
+    });
+    const body: any = await res.json().catch(() => null);
+
+    if (res.status === 429) return { kind: 'rate_limited', message: asString(body?.error) ?? MSG_RATE_LIMITED };
+    if (body?.requiresTwoFactor) return { kind: 'two_factor', codeRequest: readCodeRequest(body) };
+    if (!res.ok || body?.success !== true) {
+      return { kind: 'error', message: asString(body?.error) ?? MSG_CANNOT_SIGN_IN, offerEmailCode: body?.offerEmailCode === true };
+    }
+    return { kind: 'success' };
+  } catch {
+    return { kind: 'error', message: MSG_UNEXPECTED, offerEmailCode: false };
+  }
+}
+
+export type EmailCodeResult =
+  | { kind: 'requested'; codeRequest: CodeRequest; devCode: string | null }
+  | { kind: 'error'; message: string };
+
+export const MSG_EMAIL_CODE_FAILED = 'We could not ask for an email code just now. Try again shortly.';
+
+/** "Email me a code instead": asks the door to email a code. `requested` means asked, never arrived. */
+export async function requestEmailCode(fetchImpl: FetchLike = (input, init) => fetch(input, init)): Promise<EmailCodeResult> {
+  try {
+    const res = await fetchImpl(CREDENTIAL_EMAIL_CODE_URL, { method: 'POST', credentials: 'include' });
+    const body: any = await res.json().catch(() => null);
+    if (res.ok && body?.success === true) {
+      return {
+        kind: 'requested',
+        codeRequest: readCodeRequest(body),
+        devCode: typeof body?.devVerificationCode === 'string' && body.devVerificationCode ? body.devVerificationCode : null,
+      };
+    }
+    return { kind: 'error', message: asString(body?.error) ?? MSG_EMAIL_CODE_FAILED };
+  } catch {
+    return { kind: 'error', message: MSG_EMAIL_CODE_FAILED };
+  }
+}
+
+export { NO_CODE_REQUEST };