@payez/next-mvp 4.5.6 → 4.7.9

package/dist/auth/idp-oauth.js

@@ -0,0 +1,280 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLOCK_TOLERANCE_SECONDS = void 0;
+exports.resolveIdpRedirectUri = resolveIdpRedirectUri;
+exports.amrIncludesMfa = amrIncludesMfa;
+exports.isAddressShaped = isAddressShaped;
+exports.resolveEmail = resolveEmail;
+exports.createIdpOAuthHooks = createIdpOAuthHooks;
+/**
+ * PAY-2305 (next-mvp 4.7.4): the two hooks that let better-auth's genericOAuth talk to THIS IdP.
+ *
+ * WHY THEY EXIST (source read, PayEz-Core master d53f192af, BAPert 74014):
+ *   - POST /api/oauth/token takes a JSON body (snake_case), not better-auth's default form body, and answers with the
+ *     Core response envelope { success, data: { access_token, refresh_token, token_type, expires_in, user } }.
+ *     better-auth's default exchange reads top-level fields and would find nothing.
+ *   - There is NO id_token and NO userinfo endpoint (deliberate, PAY-1585). The only proof of who signed in is the
+ *     access token itself: an RS-family bearer JWT (RS512 on dev-93's JWKS, measured) signed by the IdP bearer key (jwks_uri in discovery) with sub, email,
+ *     roles, amr, token_type.
+ *
+ * TRUST RULE: a claim is read ONLY from a token whose signature, issuer, expiry and token_type were verified here.
+ * Never base64-decode and believe. Only RSA signatures are accepted (the RS and PS families; the JWKS key's own declared alg is binding), so a token
+ * re-signed with HS256 using the public key as the secret, or alg none, is refused. The `aud` of an IdP bearer is the IdP's public constant, not this client, so it is not a
+ * binding; the binding to THIS client is the authorization code + PKCE verifier + exact redirect_uri that Core checks.
+ *
+ * The redirect_uri sent here MUST be byte-identical at the authorize step and the token step (Core compares it
+ * Ordinal at the token step) and equal to the registered {site_url}/api/auth/callback (Core compares it exactly,
+ * case-insensitively, at the authorize step). Both come from ONE value: the `redirectURI` of the provider config.
+ */
+const jose_1 = require("jose");
+const DISCOVERY_TTL_MS = 10 * 60 * 1000;
+const HTTP_TIMEOUT_MS = 10_000;
+/** The URI sent at authorize AND token time. Explicit env wins; else the registered {app}/api/auth/callback form. */
+function resolveIdpRedirectUri(appBaseUrl, env = process.env) {
+    const explicit = env.IDP_OAUTH_REDIRECT_URI?.trim();
+    if (explicit)
+        return explicit;
+    return appBaseUrl.replace(/\/+$/, '') + '/api/auth/callback';
+}
+/** amr arrives as an array, a JSON-array string, or a delimited string (Core's own reader accepts all three). */
+function amrIncludesMfa(amr) {
+    let values = [];
+    if (Array.isArray(amr))
+        values = amr;
+    else if (typeof amr === 'string') {
+        const t = amr.trim();
+        if (t.startsWith('[')) {
+            try {
+                const parsed = JSON.parse(t);
+                if (Array.isArray(parsed))
+                    values = parsed;
+            }
+            catch {
+                values = [];
+            }
+        }
+        else {
+            values = t.split(/[\s,]+/);
+        }
+    }
+    return values.some((v) => typeof v === 'string' && v.trim().toLowerCase() === 'mfa');
+}
+/** Max skew accepted on nbf/exp/iat when verifying the IdP access token. */
+exports.CLOCK_TOLERANCE_SECONDS = 30;
+/**
+ * Address shape, a POSITIVE character rule (PAY-2337, Scout 74285): the local part may contain only [A-Za-z0-9] and . _ % + - ' ; the domain only
+ * [A-Za-z0-9-] labels joined by dots; one @, <= 254 total, local <= 64, no leading/trailing/double dot in the local part, a dotted domain.
+ * Everything else is NOT an address, and in particular a MASK: Core masks data.user.email on purpose (MaskedEmailJsonConverter), today with '*',
+ * tomorrow maybe a bullet, an ellipsis or an 'x' run; a blacklist of one glyph would pass the next mask. Not a deliverability check.
+ */
+function isAddressShaped(v) {
+    if (typeof v !== 'string' || v.length === 0 || v.length > 254)
+        return false;
+    if (!/^[A-Za-z0-9._%+'-]+@[A-Za-z0-9.-]+$/.test(v))
+        return false;
+    const [local, domain] = v.split('@');
+    if (local.length > 64 || local.startsWith('.') || local.endsWith('.') || local.includes('..'))
+        return false;
+    return /^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$/.test(domain) && !domain.startsWith('-') && !domain.endsWith('-');
+}
+/**
+ * The account address (BAPert 74193 / 74196, 4.7.8). Core's code-flow access token has NO email claim; its sub and ws-identity name claim are
+ * both user.UserName, which is a LOGIN, not the mailbox: it may be address-shaped and still differ from the account's Email (4.7.7 vetoed on that
+ * and refused every such sign-in, NightHawk 74189). Sources: the token RESPONSE's data.user.email (token endpoint, TLS) and/or the signed token's
+ * own email claim; if both are present they must be equal. sub / the name claim are NEITHER a source NOR a veto. Not trimmed. Returns '' on any doubt.
+ */
+function resolveEmail(payload, responseEmail) {
+    // NOT trimmed: padding or a trailing newline is a malformed address (refused by the shape check), never silently repaired.
+    const raw = (v) => (typeof v === 'string' ? v : '');
+    const sources = [raw(payload.email), raw(responseEmail)].filter((v) => v.trim() !== '');
+    if (sources.length === 0 || !sources.every(isAddressShaped))
+        return '';
+    const chosen = sources[0];
+    const same = (a) => a.toLowerCase() === chosen.toLowerCase();
+    if (!sources.every(same))
+        return '';
+    return chosen;
+}
+function rolesOf(claim) {
+    if (Array.isArray(claim))
+        return claim.filter((r) => typeof r === 'string' && r.length > 0);
+    if (typeof claim === 'string' && claim.trim()) {
+        const t = claim.trim();
+        if (t.startsWith('[')) {
+            try {
+                const parsed = JSON.parse(t);
+                if (Array.isArray(parsed))
+                    return parsed.filter((r) => typeof r === 'string' && r.length > 0);
+            }
+            catch {
+                return [];
+            }
+        }
+        return t.split(/[\s,]+/).filter(Boolean);
+    }
+    return [];
+}
+function createIdpOAuthHooks(opts) {
+    const fetchFn = opts.deps?.fetch ?? fetch;
+    const now = opts.deps?.now ?? (() => Date.now());
+    const getKeySet = opts.deps?.getKeySet ?? ((uri) => (0, jose_1.createRemoteJWKSet)(new URL(uri)));
+    let discovery = null;
+    const keySets = new Map();
+    /** access token -> data.user.email / user_name from the token response, consumed by getUserInfo for THAT token (bounded; never keyed by anything shared). */
+    const responseUsers = new Map();
+    async function loadDiscovery() {
+        if (discovery && now() - discovery.at < DISCOVERY_TTL_MS)
+            return discovery.doc;
+        const res = await fetchFn(opts.discoveryUrl, {
+            headers: { Accept: 'application/json' },
+            redirect: 'error',
+            signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            throw new Error(`IdP discovery returned ${res.status}`);
+        const doc = (await res.json());
+        if (typeof doc?.token_endpoint !== 'string' || typeof doc?.jwks_uri !== 'string' || typeof doc?.issuer !== 'string') {
+            throw new Error('IdP discovery document is missing token_endpoint, jwks_uri or issuer');
+        }
+        const allowed = new Set([new URL(opts.discoveryUrl).origin, ...(opts.trustedOrigins ?? []).map((o) => o.replace(/\/+$/, ''))]);
+        for (const field of ['token_endpoint', 'jwks_uri']) {
+            const origin = new URL(doc[field]).origin;
+            if (!allowed.has(origin))
+                throw new Error(`IdP discovery ${field} points at an untrusted origin (${origin})`);
+        }
+        discovery = { doc, at: now() }; // only a good document is cached
+        return doc;
+    }
+    /** better-auth `getToken`: JSON body, envelope unwrapped, no data.access_token => refused. */
+    async function getToken(data) {
+        const doc = await loadDiscovery();
+        if (!data.codeVerifier)
+            throw new Error('IdP token exchange refused: no PKCE code_verifier');
+        const res = await fetchFn(doc.token_endpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+            redirect: 'error',
+            signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+            body: JSON.stringify({
+                grant_type: 'authorization_code',
+                code: data.code,
+                code_verifier: data.codeVerifier,
+                // Deliberately NOT data.redirectURI: that is better-auth's own computed callback, not the registered URI.
+                redirect_uri: opts.redirectURI,
+                client_id: opts.clientId,
+            }),
+        });
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            throw new Error(`IdP token response (${res.status}) was not JSON`);
+        }
+        if (!res.ok) {
+            const code = body?.error?.code ?? body?.error ?? body?.code ?? 'unknown';
+            throw new Error(`IdP token exchange refused (${res.status}, ${typeof code === 'string' ? code : 'unknown'})`);
+        }
+        const d = body?.data;
+        if (!d || typeof d.access_token !== 'string' || !d.access_token) {
+            throw new Error('IdP token response has no data.access_token (envelope not as expected)');
+        }
+        const expiresIn = typeof d.expires_in === 'number' && d.expires_in > 0 ? d.expires_in : undefined;
+        const expires = expiresIn ? now() + expiresIn * 1000 : undefined;
+        if (d.user && typeof d.user === 'object' && typeof d.user.email === 'string') {
+            if (responseUsers.size >= 64)
+                responseUsers.delete(responseUsers.keys().next().value);
+            responseUsers.set(d.access_token, { email: d.user.email, userName: typeof d.user.user_name === 'string' ? d.user.user_name : '' });
+        }
+        opts.onTokens?.({
+            accessToken: d.access_token,
+            refreshToken: typeof d.refresh_token === 'string' ? d.refresh_token : undefined,
+            accessTokenExpires: expires,
+            tokenType: typeof d.token_type === 'string' ? d.token_type : undefined,
+            user: d.user && typeof d.user === 'object' ? d.user : undefined,
+        });
+        return {
+            tokenType: typeof d.token_type === 'string' ? d.token_type : 'Bearer',
+            accessToken: d.access_token,
+            refreshToken: typeof d.refresh_token === 'string' ? d.refresh_token : undefined,
+            accessTokenExpiresAt: expires ? new Date(expires) : undefined,
+            scopes: [],
+        };
+    }
+    /** better-auth `getUserInfo`: the user comes from the VERIFIED access token. Returns null (never a guess) on any doubt. */
+    async function getUserInfo(tokens) {
+        try {
+            if (!tokens?.accessToken)
+                return null;
+            const doc = await loadDiscovery();
+            // A token without a kid is refused: no "first key" fallback. (A kid that is not in the key set is refused by jose.)
+            const kid = (0, jose_1.decodeProtectedHeader)(tokens.accessToken).kid;
+            if (typeof kid !== 'string' || !kid)
+                throw new Error('token header has no kid');
+            const jwksUri = doc.jwks_uri;
+            let keys = keySets.get(jwksUri);
+            if (!keys) {
+                keys = getKeySet(jwksUri);
+                keySets.set(jwksUri, keys);
+            }
+            const { payload } = await (0, jose_1.jwtVerify)(tokens.accessToken, keys, {
+                // RSA signatures ONLY (RS256/384/512, PS256/384/512; BAPert 74117): never HS* (a token "signed" with the public key as an HMAC
+                // secret), never none, never ES. 4.7.4/4.7.5 pinned RS256 from a source read; the live IdP's JWKS (dev-93, kid 46) declares alg RS512
+                // and every real access token was refused (NightHawk 74114). Which RS alg is binding is the JWKS KEY's own declared
+                // `alg`: jose only offers a JWK to a token whose header alg equals that JWK's `alg`, so a token cannot choose a
+                // weaker/other algorithm than the published key says. A JWK with no `alg` accepts any listed RSA alg; a symmetric (oct) key is never usable for these algorithms.
+                algorithms: ['RS256', 'RS384', 'RS512', 'PS256', 'PS384', 'PS512'],
+                issuer: opts.issuer ?? doc.issuer,
+                currentDate: new Date(now()),
+                // The IdP stamps nbf = issue time with no skew and the token is verified in the same second it is minted (NightHawk 74151:
+                // "nbf claim timestamp check failed"). 30 s, bounded. jose applies it to exp too: a token is accepted up to 30 s after exp.
+                clockTolerance: exports.CLOCK_TOLERANCE_SECONDS,
+            });
+            if (payload.token_type !== 'bearer_token')
+                throw new Error('token_type is not bearer_token');
+            if (typeof payload.sub !== 'string' || !payload.sub)
+                throw new Error('no sub');
+            const hasEmailClaim = typeof payload.email === 'string' && payload.email.trim() !== '';
+            const responseUser = responseUsers.get(tokens.accessToken);
+            responseUsers.delete(tokens.accessToken);
+            // The response user object (UNSIGNED body) must be the TOKEN's user (Scout 74198, DotNetPert-Scout 74202): Core fills data.user.user_name and the
+            // signed sub from the same loaded user in one mint, so WHENEVER a response user exists (even if a signed email claim is also present), user_name MUST be present
+            // and equal sub (case-insensitive). A different or missing user_name means the address may belong to someone else -> refuse. Does not constrain email == sub.
+            if (responseUser && responseUser.userName.trim().toLowerCase() !== payload.sub.trim().toLowerCase()) {
+                throw new Error('token response user is missing or does not match the token subject');
+            }
+            // A MASKED / unusable response address is ABSENT (PAY-2337), not "a different address": a valid signed claim still signs in, and with no claim
+            // there is no source. NEVER repaired or unmasked (no prefix match against sub or the claim). Log names only the fact, no value, no length.
+            const responseEmailRaw = responseUser?.email ?? '';
+            const responseEmailUsable = isAddressShaped(responseEmailRaw);
+            const responseMasked = responseEmailRaw.trim() !== '' && !responseEmailUsable;
+            if (responseMasked)
+                console.warn('[BETTER_AUTH] payez-idp token response address is masked or unusable; ignored');
+            const email = resolveEmail(payload, responseEmailUsable ? responseEmailRaw : undefined);
+            if (!email) {
+                throw new Error(responseMasked ? 'response address is masked' : 'no usable email (needs data.user.email or an email claim, address-shaped, equal when both are present)');
+            }
+            const name = (typeof payload.name === 'string' && payload.name.trim()) ||
+                (typeof payload.full_name === 'string' && payload.full_name.trim()) ||
+                email.split('@')[0];
+            const claims = {
+                sub: payload.sub,
+                email,
+                name,
+                userId: typeof payload.user_id === 'string' || typeof payload.user_id === 'number' ? String(payload.user_id) : undefined,
+                roles: rolesOf(payload.roles),
+                mfaVerified: amrIncludesMfa(payload.amr),
+                // Only the signed token's own email CLAIM can be verified; an address that came from the token response (data.user.email) never asserts it.
+                emailVerified: hasEmailClaim && (payload.email_verified === true || payload.email_verified === 'true'),
+            };
+            opts.onClaims?.(claims);
+            return { id: claims.sub, email: claims.email, name: claims.name, emailVerified: claims.emailVerified };
+        }
+        catch (err) {
+            // Reason only, never the token.
+            console.warn('[BETTER_AUTH] payez-idp access token refused:', err instanceof Error ? err.message : String(err));
+            return null;
+        }
+    }
+    return { getToken, getUserInfo };
+}

package/dist/auth/safe-callback.js

@@ -68,6 +68,14 @@ exports.resolveCallbackDestination = resolveCallbackDestination;
 exports.DEFAULT_CALLBACK = '/';
 /** The auth surface. A callback pointing back into it causes a redirect cycle. */
 const AUTH_PREFIX = '/account-auth/';
+/**
+ * PAY-2315 (4.7.1): the middleware now treats the public /login page like /account-auth/login (a signed-in user is sent
+ * on), so a callback or a resolved path that is /login itself must be refused here too - otherwise /login with no
+ * callbackUrl would resolve its own pathname as the destination and redirect to itself forever.
+ */
+function isAuthSurface(pathname) {
+    return pathname.startsWith(AUTH_PREFIX) || pathname === '/login' || pathname.startsWith('/login/');
+}
 /**
  * Synthetic, unreachable base. Only ever used as the resolution origin for the
  * comparison below - never emitted, never navigated to. `.invalid` is reserved
@@ -95,8 +103,13 @@ function safeCallbackPath(raw, fallback = exports.DEFAULT_CALLBACK) {
     if (url.origin !== BASE)
         return fallback;
     // Loopbacks into the auth surface cause redirect cycles.
-    if (url.pathname.startsWith(AUTH_PREFIX))
+    if (isAuthSurface(url.pathname))
         return fallback;
+    // PAY-2218: `_rsc` is Next's flight cache-buster. Once skipProxyUrlNormalize lets it reach middleware it leaks
+    // into return targets (`callbackUrl=/overview?_rsc=abc12`, NightHawk 72013); it is never a meaningful part of a
+    // destination. Only touched when present, so every other query keeps its exact spelling.
+    if (url.searchParams.has('_rsc'))
+        url.searchParams.delete('_rsc');
     // The parser's normalised output - control characters already stripped.
     const candidate = url.pathname + url.search + url.hash;
     // *** SECOND RESOLUTION. DO NOT DELETE THIS AS REDUNDANT - IT IS NOT. ***
@@ -138,7 +151,7 @@ function safeCallbackPath(raw, fallback = exports.DEFAULT_CALLBACK) {
     }
     if (echo.origin !== BASE)
         return fallback;
-    if (echo.pathname.startsWith(AUTH_PREFIX))
+    if (isAuthSurface(echo.pathname))
         return fallback;
     if (echo.pathname + echo.search + echo.hash !== candidate)
         return fallback;

package/dist/auth/session-cookie-clear.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The ONE body that writes the session-cookie expiry Set-Cookie headers. Shared by the middleware
+ * (create-middleware.ts clearSessionCookies, behind its prefetch guard) and the PAY-2218 session-reset route, so
+ * the two clearing sites cannot drift apart on which cookies they expire or with which attributes.
+ */
+import type { NextResponse } from 'next/server';
+export declare function expireSessionCookies(response: NextResponse, requestCookieNames: Iterable<string>): void;

package/dist/auth/session-cookie-clear.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expireSessionCookies = expireSessionCookies;
+const app_slug_1 = require("../lib/app-slug");
+function expireSessionCookies(response, requestCookieNames) {
+    const sessionCookie = (0, app_slug_1.getSessionCookieName)();
+    const secureCookie = (0, app_slug_1.getSecureSessionCookieName)();
+    // Clear main cookies
+    response.cookies.set(sessionCookie, '', { path: '/', expires: new Date(0), httpOnly: true, sameSite: 'lax' });
+    response.cookies.set(secureCookie, '', { path: '/', expires: new Date(0), httpOnly: true, sameSite: 'lax', secure: true });
+    // Clear any chunked cookies (NextAuth chunks large cookies)
+    for (const name of requestCookieNames) {
+        if (name.startsWith(`${sessionCookie}.`) || name.startsWith(`${secureCookie}.`)) {
+            const isSecure = name.startsWith('__Secure-');
+            response.cookies.set(name, '', {
+                path: '/',
+                expires: new Date(0),
+                httpOnly: true,
+                sameSite: 'lax',
+                ...(isSecure && { secure: true })
+            });
+        }
+    }
+}

package/dist/auth/session-reset-link.d.ts

@@ -0,0 +1,43 @@
+export declare const LOGIN_PAGE = "/account-auth/login";
+/** The mount point consumers use: `app/api/auth/session-reset/route.ts` (under /api/auth/, which middleware bypasses). */
+export declare const DEFAULT_SESSION_RESET_ROUTE = "/api/auth/session-reset";
+/** How long a signed reset link stays valid. A real navigation follows the 307 at once; this only bounds replay. */
+export declare const RESET_LINK_TTL_SECONDS = 300;
+/** The purpose label for the derived signing key. Changing it invalidates every outstanding reset link. */
+export declare const RESET_KEY_PURPOSE = "next-mvp/session-reset/v1";
+/** The only `reason` / `error` values the middleware emits on a clearing redirect. Anything else is dropped. */
+export declare const RESET_REASONS: readonly string[];
+export declare const RESET_ERRORS: readonly string[];
+export interface ResetParams {
+    callbackUrl: string;
+    reason?: string;
+    error?: string;
+}
+/** The secret the app already signs its session cookie with. Undefined means "cannot sign": callers fall back. */
+export declare function resetSecret(): string | undefined;
+/** The session cookie a reset is bound to: the __Secure- one when present, else the plain one. */
+export declare function boundSessionCookie(get: (name: string) => string | undefined, plainName: string, secureName: string): string | undefined;
+/** Normalise to exactly what the route will honour, so what is signed is what is verified. */
+export declare function normaliseResetParams(raw: {
+    callbackUrl?: string | null;
+    reason?: string | null;
+    error?: string | null;
+}): ResetParams;
+/** What the signature covers. Exported for the key-separation row, which signs it with the RAW secret. */
+export declare function resetPayload(p: ResetParams, exp: number, binding: string): string;
+/** The login URL for these params, in the exact shape the middleware has always emitted. */
+export declare function loginLocation(p: ResetParams): string;
+/**
+ * Path + query for the reset route, bound to `sessionCookieValue` (the session cookie on the request being ended).
+ * `nowMs` is injectable for tests.
+ */
+export declare function signedResetHref(route: string, p: ResetParams, secret: string, sessionCookieValue: string | undefined, nowMs?: number): Promise<string>;
+/**
+ * Read a reset request's query. `signed` is true only for a valid, unexpired signature over the normalised params AND
+ * this request's own session cookie (`sessionCookieValue`). With no session cookie there is nothing to clear: false.
+ * The params are returned either way: an unsigned request still gets a sensible login redirect, just no clearing.
+ */
+export declare function readResetRequest(search: URLSearchParams, secret: string | undefined, sessionCookieValue: string | undefined, nowMs?: number): Promise<{
+    params: ResetParams;
+    signed: boolean;
+}>;

package/dist/auth/session-reset-link.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESET_ERRORS = exports.RESET_REASONS = exports.RESET_KEY_PURPOSE = exports.RESET_LINK_TTL_SECONDS = exports.DEFAULT_SESSION_RESET_ROUTE = exports.LOGIN_PAGE = void 0;
+exports.resetSecret = resetSecret;
+exports.boundSessionCookie = boundSessionCookie;
+exports.normaliseResetParams = normaliseResetParams;
+exports.resetPayload = resetPayload;
+exports.loginLocation = loginLocation;
+exports.signedResetHref = signedResetHref;
+exports.readResetRequest = readResetRequest;
+/**
+ * PAY-2218 PR 2: the hand-off between the middleware and the session-reset route.
+ *
+ * WHY A ROUTE AT ALL. Next 15.5.x and 16.x (16.2.x without `skipProxyUrlNormalize`) strip every router flight
+ * header (`rsc`, `next-router-prefetch`, `next-router-segment-prefetch`, `next-router-state-tree`) from the request
+ * handed to middleware, so middleware cannot tell a router prefetch from a real navigation and its prefetch guard is
+ * dead. A ROUTE HANDLER does see them, on 15.5.9, 16.1.5 and 16.2.12 (measured with a real Chromium against real
+ * `next start` servers, PAY-2218 comments 2026-10-11). So the middleware no longer writes the clearing Set-Cookie
+ * itself: it redirects to the reset route, and the route decides.
+ *
+ * WHY THE ROUTE ANSWERS A PREFETCH WITH 204, NOT A REDIRECT. On 15.5.9 the router CACHES a prefetched redirect chain
+ * and the later click reuses it without calling middleware or the route again - so "decline on the prefetch, clear
+ * on the real navigation" never clears there. A 204 + no-store gives the router nothing to cache, so the real click
+ * reaches the route and clears (measured 2/2 on 15.5.9 and 16.2.12; the 307 mutant never clears on 15.5.9).
+ *
+ * WHY SIGNED. The route clears cookies on a GET. Unsigned, any page could link a signed-in user to it and log them
+ * out. The middleware signs (callbackUrl, reason, error, exp, session binding); the route clears only on a valid,
+ * unexpired signature and otherwise just sends the user to the login page with the cookies untouched.
+ *
+ * KEY SEPARATION (BAPert 72219). The signing key is DERIVED - HMAC(authSecret, 'next-mvp/session-reset/v1') - never
+ * the raw auth secret, so no value the app signs with that secret for any other purpose can pass as a reset token.
+ *
+ * SESSION BINDING (BAPert 72219). The signature covers SHA-256 of the session cookie the redirect was issued FOR. The
+ * route recomputes it from ITS OWN request's cookie and clears only on a match, so a token captured from one user
+ * clears nothing when sent to another (logout-CSRF), and a second use is a no-op (the first use cleared the cookie it
+ * was bound to). The hash never travels in the URL; it is only an input to the signature.
+ *
+ * WHY THE ROUTE REBUILDS THE LOGIN URL. The route never redirects to a URL it was handed. It takes `callbackUrl`
+ * (through safeCallbackPath), `reason` and `error` (allowlisted) and builds `${LOGIN_PAGE}?...` itself, so it cannot
+ * become an open redirect whatever the query says.
+ *
+ * Edge-safe: Web Crypto only (middleware runs on the edge runtime on 15.5.x).
+ */
+const safe_callback_1 = require("./safe-callback");
+exports.LOGIN_PAGE = '/account-auth/login';
+/** The mount point consumers use: `app/api/auth/session-reset/route.ts` (under /api/auth/, which middleware bypasses). */
+exports.DEFAULT_SESSION_RESET_ROUTE = '/api/auth/session-reset';
+/** How long a signed reset link stays valid. A real navigation follows the 307 at once; this only bounds replay. */
+exports.RESET_LINK_TTL_SECONDS = 300;
+/** The purpose label for the derived signing key. Changing it invalidates every outstanding reset link. */
+exports.RESET_KEY_PURPOSE = 'next-mvp/session-reset/v1';
+/** The only `reason` / `error` values the middleware emits on a clearing redirect. Anything else is dropped. */
+exports.RESET_REASONS = ['stale', 'invalidated'];
+exports.RESET_ERRORS = ['SessionExpired', 'TwoFactorTimeout'];
+const encoder = new TextEncoder();
+const FIELD_SEPARATOR = String.fromCharCode(10);
+function b64url(bytes) {
+    return btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+async function hmacBytes(key, message) {
+    const k = await crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return new Uint8Array(await crypto.subtle.sign('HMAC', k, encoder.encode(message)));
+}
+/** Sign with the DERIVED key: HMAC(HMAC(authSecret, purpose), message). Never with the raw auth secret. */
+async function sign(secret, message) {
+    const derived = await hmacBytes(encoder.encode(secret), exports.RESET_KEY_PURPOSE);
+    return b64url(await hmacBytes(derived, message));
+}
+/** SHA-256 of the session cookie value, b64url. No session cookie binds to the empty string. */
+async function sessionBinding(sessionCookieValue) {
+    if (!sessionCookieValue)
+        return '';
+    return b64url(new Uint8Array(await crypto.subtle.digest('SHA-256', encoder.encode(sessionCookieValue))));
+}
+/** Constant-time over equal lengths, and unequal lengths never match. */
+function sameString(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/** The secret the app already signs its session cookie with. Undefined means "cannot sign": callers fall back. */
+function resetSecret() {
+    return process.env.BETTER_AUTH_SECRET || process.env.NEXTAUTH_SECRET || undefined;
+}
+/** The session cookie a reset is bound to: the __Secure- one when present, else the plain one. */
+function boundSessionCookie(get, plainName, secureName) {
+    return get(secureName) || get(plainName) || undefined;
+}
+/** Normalise to exactly what the route will honour, so what is signed is what is verified. */
+function normaliseResetParams(raw) {
+    const out = { callbackUrl: (0, safe_callback_1.safeCallbackPath)(raw.callbackUrl ?? '') };
+    if (raw.reason && exports.RESET_REASONS.includes(raw.reason))
+        out.reason = raw.reason;
+    if (raw.error && exports.RESET_ERRORS.includes(raw.error))
+        out.error = raw.error;
+    return out;
+}
+/** What the signature covers. Exported for the key-separation row, which signs it with the RAW secret. */
+function resetPayload(p, exp, binding) {
+    return ['v2', p.callbackUrl, p.reason ?? '', p.error ?? '', String(exp), binding].join(FIELD_SEPARATOR);
+}
+/** The login URL for these params, in the exact shape the middleware has always emitted. */
+function loginLocation(p) {
+    let loc = `${exports.LOGIN_PAGE}?callbackUrl=${encodeURIComponent(p.callbackUrl)}`;
+    if (p.reason)
+        loc += `&reason=${p.reason}`;
+    if (p.error)
+        loc += `&error=${p.error}`;
+    return loc;
+}
+/**
+ * Path + query for the reset route, bound to `sessionCookieValue` (the session cookie on the request being ended).
+ * `nowMs` is injectable for tests.
+ */
+async function signedResetHref(route, p, secret, sessionCookieValue, nowMs = Date.now()) {
+    const exp = Math.floor(nowMs / 1000) + exports.RESET_LINK_TTL_SECONDS;
+    const q = new URLSearchParams({ callbackUrl: p.callbackUrl });
+    if (p.reason)
+        q.set('reason', p.reason);
+    if (p.error)
+        q.set('error', p.error);
+    q.set('exp', String(exp));
+    q.set('sig', await sign(secret, resetPayload(p, exp, await sessionBinding(sessionCookieValue))));
+    return `${route}?${q.toString()}`;
+}
+/**
+ * Read a reset request's query. `signed` is true only for a valid, unexpired signature over the normalised params AND
+ * this request's own session cookie (`sessionCookieValue`). With no session cookie there is nothing to clear: false.
+ * The params are returned either way: an unsigned request still gets a sensible login redirect, just no clearing.
+ */
+async function readResetRequest(search, secret, sessionCookieValue, nowMs = Date.now()) {
+    const params = normaliseResetParams({ callbackUrl: search.get('callbackUrl'), reason: search.get('reason'), error: search.get('error') });
+    const sig = search.get('sig');
+    const exp = Number(search.get('exp'));
+    if (!secret || !sig || !sessionCookieValue || !Number.isInteger(exp) || exp < Math.floor(nowMs / 1000))
+        return { params, signed: false };
+    // The signature covers the NORMALISED params and THIS request's session, so a tampered value, or the token arriving
+    // with a different session cookie (another user, or the same user after signing in again), fails here.
+    const want = await sign(secret, resetPayload(params, exp, await sessionBinding(sessionCookieValue)));
+    return { params, signed: sameString(sig, want) };
+}

package/dist/components/auth/CredentialSignInForm.d.ts

@@ -0,0 +1,33 @@
+import { 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;
+}
+export declare function resolveDestination(explicit?: string): string;
+export declare function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPassword }: Props): import("react/jsx-runtime").JSX.Element;
+export default CredentialSignInForm;