@payez/next-mvp 4.5.7 → 4.7.9

package/dist/lib/authorize-resume.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTHORIZE_RESUME_ROUTE = void 0;
+exports.isIdpAuthorizeUrl = isIdpAuthorizeUrl;
+exports.idpAuthorizeRedirect = idpAuthorizeRedirect;
+exports.authorizeResumeHref = authorizeResumeHref;
+exports.buildServerAuthorizeRequest = buildServerAuthorizeRequest;
+exports.relayRegisteredCallback = relayRegisteredCallback;
+exports.isSameSiteResume = isSameSiteResume;
+exports.hasOAuthStateCookie = hasOAuthStateCookie;
+/**
+ * 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.
+ */
+exports.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). */
+function isIdpAuthorizeUrl(candidate, idpBaseUrl) {
+    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.
+ */
+function idpAuthorizeRedirect(candidate, idpBaseUrl) {
+    if (!isIdpAuthorizeUrl(candidate, idpBaseUrl))
+        return null;
+    const query = new URL(candidate).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.
+ */
+function authorizeResumeHref(returnUrl) {
+    if (typeof returnUrl !== 'string' || returnUrl === '')
+        return null;
+    const query = new URLSearchParams({ return_url: returnUrl }).toString().replace(/\*/g, '%2A');
+    return `${exports.AUTHORIZE_RESUME_ROUTE}?${query}`;
+}
+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.
+ */
+function buildServerAuthorizeRequest(returnUrl, p) {
+    if (!isIdpAuthorizeUrl(returnUrl, p.idpBaseUrl) || !p.clientId || !p.redirectUri)
+        return null;
+    const q = new URL(returnUrl).searchParams;
+    const once = (name) => {
+        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.
+ */
+function relayRegisteredCallback(status, location, redirectUri, sentState) {
+    if (status < 300 || status > 399 || typeof location !== 'string' || location === '')
+        return null;
+    let loc;
+    let reg;
+    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).
+ */
+function isSameSiteResume(headers, appOrigin) {
+    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.
+ */
+function hasOAuthStateCookie(cookieHeader) {
+    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/dist/lib/bearer-fetch.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 declare const REDIRECT_REFUSED_CODE = "IDP_UNREACHABLE";
+export declare function isRedirectResponse(res: Response): boolean;
+export declare function bearerFetch(input: string | URL, init?: RequestInit): Promise<Response>;

package/dist/lib/bearer-fetch.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REDIRECT_REFUSED_CODE = void 0;
+exports.isRedirectResponse = isRedirectResponse;
+exports.bearerFetch = bearerFetch;
+/**
+ * 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.
+ */
+exports.REDIRECT_REFUSED_CODE = 'IDP_UNREACHABLE';
+function isRedirectResponse(res) {
+    return res.type === 'opaqueredirect' || (res.status >= 300 && res.status < 400);
+}
+async function bearerFetch(input, init = {}) {
+    const res = await fetch(input, { ...init, redirect: 'manual' });
+    if (!isRedirectResponse(res))
+        return res;
+    return new Response(JSON.stringify({
+        success: false,
+        error: { code: exports.REDIRECT_REFUSED_CODE, message: 'The identity service answered with a redirect; the call was not followed' },
+    }), { status: 502, headers: { 'Content-Type': 'application/json' } });
+}

package/dist/lib/code-step-copy.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 declare const NO_CODE_REQUEST: CodeRequest;
+/**
+ * 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 declare function readCodeRequest(body: unknown): CodeRequest;
+/**
+ * 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 declare function codeStepParts(r: CodeRequest): {
+    before: string;
+    after: string;
+};
+/** The sentence as one plain string, for a card whose subtitle prop is a string. */
+export declare function codeStepInstruction(email: string, r: CodeRequest): string;

package/dist/lib/code-step-copy.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * 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".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_CODE_REQUEST = void 0;
+exports.readCodeRequest = readCodeRequest;
+exports.codeStepParts = codeStepParts;
+exports.codeStepInstruction = codeStepInstruction;
+/** Nothing sent, nothing to say beyond the authenticator. What a card starts with. */
+exports.NO_CODE_REQUEST = { 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.
+ */
+function readCodeRequest(body) {
+    const b = body && typeof body === 'object' ? body : {};
+    const sentVia = b.sentVia === 'sms' || b.sentVia === 'email' ? b.sentVia : null;
+    const accepted = Array.isArray(b.acceptedFactors) ? b.acceptedFactors : null;
+    const base = { 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) {
+    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.
+ */
+function codeStepParts(r) {
+    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. */
+function codeStepInstruction(email, r) {
+    const { before, after } = codeStepParts(r);
+    return `${before}${email}${after}`;
+}

package/dist/lib/credential-sign-in-client.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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, type CodeRequest } from './code-step-copy';
+export declare const CREDENTIAL_LOGIN_URL = "/api/auth/admin-login";
+export declare 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 declare const MSG_RATE_LIMITED = "Too many attempts. Please try again later.";
+export declare const MSG_CANNOT_SIGN_IN = "Could not sign in. Check your details and try again.";
+export declare const MSG_UNEXPECTED = "Something went wrong signing you in. Please try again.";
+export declare function isEmailShaped(v: string): boolean;
+/** Field-level checks before anything is sent. Returns the errors, or null when the input may be submitted. */
+export declare function validateCredentials(email: string, password: string): {
+    email?: string;
+    password?: string;
+} | null;
+/** One call to the credential door. `code` is the 2FA code on the second turn; email and password are resubmitted with it. */
+export declare function credentialSignIn(args: {
+    email: string;
+    password: string;
+    code?: string;
+}, fetchImpl?: FetchLike): Promise<CredentialSignInResult>;
+export type EmailCodeResult = {
+    kind: 'requested';
+    codeRequest: CodeRequest;
+    devCode: string | null;
+} | {
+    kind: 'error';
+    message: string;
+};
+export declare 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 declare function requestEmailCode(fetchImpl?: FetchLike): Promise<EmailCodeResult>;
+export { NO_CODE_REQUEST };

package/dist/lib/credential-sign-in-client.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_CODE_REQUEST = exports.MSG_EMAIL_CODE_FAILED = exports.MSG_UNEXPECTED = exports.MSG_CANNOT_SIGN_IN = exports.MSG_RATE_LIMITED = exports.CREDENTIAL_EMAIL_CODE_URL = exports.CREDENTIAL_LOGIN_URL = void 0;
+exports.isEmailShaped = isEmailShaped;
+exports.validateCredentials = validateCredentials;
+exports.credentialSignIn = credentialSignIn;
+exports.requestEmailCode = requestEmailCode;
+/**
+ * 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).
+ */
+const code_step_copy_1 = require("./code-step-copy");
+Object.defineProperty(exports, "NO_CODE_REQUEST", { enumerable: true, get: function () { return code_step_copy_1.NO_CODE_REQUEST; } });
+exports.CREDENTIAL_LOGIN_URL = '/api/auth/admin-login';
+exports.CREDENTIAL_EMAIL_CODE_URL = '/api/auth/admin-login/email-code';
+exports.MSG_RATE_LIMITED = 'Too many attempts. Please try again later.';
+exports.MSG_CANNOT_SIGN_IN = 'Could not sign in. Check your details and try again.';
+exports.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])?)*$/;
+function isEmailShaped(v) {
+    return EMAIL_SHAPE.test(v);
+}
+/** Field-level checks before anything is sent. Returns the errors, or null when the input may be submitted. */
+function validateCredentials(email, password) {
+    const errors = {};
+    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) {
+    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. */
+async function credentialSignIn(args, fetchImpl = (input, init) => fetch(input, init)) {
+    try {
+        const res = await fetchImpl(exports.CREDENTIAL_LOGIN_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ email: args.email, password: args.password, code: args.code }),
+        });
+        const body = await res.json().catch(() => null);
+        if (res.status === 429)
+            return { kind: 'rate_limited', message: asString(body?.error) ?? exports.MSG_RATE_LIMITED };
+        if (body?.requiresTwoFactor)
+            return { kind: 'two_factor', codeRequest: (0, code_step_copy_1.readCodeRequest)(body) };
+        if (!res.ok || body?.success !== true) {
+            return { kind: 'error', message: asString(body?.error) ?? exports.MSG_CANNOT_SIGN_IN, offerEmailCode: body?.offerEmailCode === true };
+        }
+        return { kind: 'success' };
+    }
+    catch {
+        return { kind: 'error', message: exports.MSG_UNEXPECTED, offerEmailCode: false };
+    }
+}
+exports.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. */
+async function requestEmailCode(fetchImpl = (input, init) => fetch(input, init)) {
+    try {
+        const res = await fetchImpl(exports.CREDENTIAL_EMAIL_CODE_URL, { method: 'POST', credentials: 'include' });
+        const body = await res.json().catch(() => null);
+        if (res.ok && body?.success === true) {
+            return {
+                kind: 'requested',
+                codeRequest: (0, code_step_copy_1.readCodeRequest)(body),
+                devCode: typeof body?.devVerificationCode === 'string' && body.devVerificationCode ? body.devVerificationCode : null,
+            };
+        }
+        return { kind: 'error', message: asString(body?.error) ?? exports.MSG_EMAIL_CODE_FAILED };
+    }
+    catch {
+        return { kind: 'error', message: exports.MSG_EMAIL_CODE_FAILED };
+    }
+}

package/dist/lib/device-id.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Per-browser device identity — card 240566 (QAPert flag 2 on the 9c7a815 review).
+ *
+ * BEFORE: /api/auth/admin-login forwarded ONE hardcoded device-id cookie —
+ * `payez-PayEz-6c8201c35c1b44c9b2e823b36b95a718` — for every caller on the
+ * PUBLIC /sign-in password path. To the IDP's rate limiter and device
+ * fingerprinting, every portal user was literally the same device. Two
+ * consequences, both measured-by-inspection rather than hypothetical:
+ *   1. SHARED-FATE LOCKOUT — one attacker's failed attempts consume the
+ *      throttle budget for every legitimate user at once.
+ *   2. Per-device risk signals are meaningless: "new device" and "trusted
+ *      device" cannot distinguish anybody from anybody.
+ *
+ * The id is a routing/telemetry key, NOT a credential — the IDP must never
+ * grant anything on the strength of it, and nothing here assumes otherwise.
+ * It is client-supplied and therefore client-forgeable; that is inherent to
+ * device-id throttling and is why it supplements, never replaces, the
+ * identifier- and IP-scoped limits on the IDP side.
+ *
+ * Shape is fixed by what the IDP already accepts from
+ * createLoginHandler: `payez-PayEz-<32 lowercase hex>`.
+ */
+export declare const DEVICE_ID_HEADER = "X-Device-Id";
+export declare const DEVICE_ID_PATTERN: RegExp;
+/** True for a well-formed device id. Used on BOTH sides of the wire. */
+export declare function isValidDeviceId(value: string | null | undefined): value is string;
+/**
+ * The stable per-browser device id, minted once and persisted.
+ *
+ * Browser-only. Persistence is best-effort: private windows, disabled site
+ * data and storage-quota failures all throw on access, so every read and
+ * write is guarded. A browser that cannot persist still gets a VALID id for
+ * this call — it simply looks like a new device each time, which is the
+ * honest answer for a client that refuses to be remembered, and is still
+ * strictly better than every user sharing one identity.
+ */
+export declare function getDeviceId(): string;

package/dist/lib/device-id.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Per-browser device identity — card 240566 (QAPert flag 2 on the 9c7a815 review).
+ *
+ * BEFORE: /api/auth/admin-login forwarded ONE hardcoded device-id cookie —
+ * `payez-PayEz-6c8201c35c1b44c9b2e823b36b95a718` — for every caller on the
+ * PUBLIC /sign-in password path. To the IDP's rate limiter and device
+ * fingerprinting, every portal user was literally the same device. Two
+ * consequences, both measured-by-inspection rather than hypothetical:
+ *   1. SHARED-FATE LOCKOUT — one attacker's failed attempts consume the
+ *      throttle budget for every legitimate user at once.
+ *   2. Per-device risk signals are meaningless: "new device" and "trusted
+ *      device" cannot distinguish anybody from anybody.
+ *
+ * The id is a routing/telemetry key, NOT a credential — the IDP must never
+ * grant anything on the strength of it, and nothing here assumes otherwise.
+ * It is client-supplied and therefore client-forgeable; that is inherent to
+ * device-id throttling and is why it supplements, never replaces, the
+ * identifier- and IP-scoped limits on the IDP side.
+ *
+ * Shape is fixed by what the IDP already accepts from
+ * createLoginHandler: `payez-PayEz-<32 lowercase hex>`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEVICE_ID_PATTERN = exports.DEVICE_ID_HEADER = void 0;
+exports.isValidDeviceId = isValidDeviceId;
+exports.getDeviceId = getDeviceId;
+exports.DEVICE_ID_HEADER = 'X-Device-Id';
+exports.DEVICE_ID_PATTERN = /^payez-PayEz-[0-9a-f]{32}$/;
+const STORAGE_KEY = 'payez.device-id';
+/** True for a well-formed device id. Used on BOTH sides of the wire. */
+function isValidDeviceId(value) {
+    return typeof value === 'string' && exports.DEVICE_ID_PATTERN.test(value);
+}
+function mint() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    const hex = Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+    return `payez-PayEz-${hex}`;
+}
+/**
+ * The stable per-browser device id, minted once and persisted.
+ *
+ * Browser-only. Persistence is best-effort: private windows, disabled site
+ * data and storage-quota failures all throw on access, so every read and
+ * write is guarded. A browser that cannot persist still gets a VALID id for
+ * this call — it simply looks like a new device each time, which is the
+ * honest answer for a client that refuses to be remembered, and is still
+ * strictly better than every user sharing one identity.
+ */
+function getDeviceId() {
+    if (typeof window === 'undefined')
+        return mint();
+    try {
+        const existing = window.localStorage.getItem(STORAGE_KEY);
+        if (isValidDeviceId(existing))
+            return existing;
+    }
+    catch {
+        return mint();
+    }
+    const minted = mint();
+    try {
+        window.localStorage.setItem(STORAGE_KEY, minted);
+    }
+    catch {
+        /* not persistable — the minted id is still returned and used for this call */
+    }
+    return minted;
+}

package/dist/lib/lock-window.d.ts

@@ -0,0 +1,29 @@
+/**
+ * PAY-1608: a 2FA lock's window, stated as the IdP enforces it. Never a hard-coded "15 minutes".
+ *
+ * Core answers every 2FA lock with 429 code "locked" plus Retry-After: MfaController.SecondFactorLocked sends the
+ * full lockout (900), and VerifyTotp sends what is LEFT of the lock. The portal used to hard-code "locked for 15
+ * minutes" in three places (verify-code-copy.ts, twofa-rejection.ts, and the next-mvp BFF), which was true only
+ * while every lock was exactly 15 minutes and the user had just tripped it.
+ *
+ * The window arrives in one of two ways:
+ *   - Door A (verify-code): next-mvp >= 4.5.2 relays it in the BFF body as `retryAfterSeconds` (a number).
+ *   - Door B (admin-login): this route reads the IdP's Retry-After header itself.
+ * With no window, the sentence states NO number rather than a guessed one.
+ *
+ * Dependency-free on purpose: the verify-code page (client) and the admin-login route (server) both use it, and
+ * the chain gate executes it directly.
+ */
+/** A positive whole number of seconds from the BFF body, or undefined. Anything else - a string, 0, NaN - is dropped. */
+export declare function lockSecondsFromBody(value: unknown): number | undefined;
+/** A Retry-After header as whole seconds. ONE implementation: the package's lib/retry-after (the portal copy was the same rule). */
+export { parseRetryAfterSeconds } from './retry-after';
+/**
+ * The window in words, rounded UP so the user is never told a shorter wait than the IdP enforces:
+ * 900 -> "15 minutes", 61 -> "2 minutes", 60 -> "1 minute", 45 -> "45 seconds", 7200 -> "2 hours".
+ */
+export declare function formatLockWindow(seconds: number | undefined): string | undefined;
+/** The sentence for a lock whose window was NOT sent. It says even a correct code is refused, and states no number. */
+export declare const LOCKED_NO_WINDOW = "Too many incorrect codes. Verification is locked for now - even a correct code is refused until the lock ends. Wait before entering another code.";
+/** The locked sentence: the IdP's real window when it sent one, otherwise LOCKED_NO_WINDOW. */
+export declare function lockedSentence(seconds?: number): string;