@payez/next-mvp 4.4.5 → 4.4.7

package/dist/components/admin/DataBrowserTab.js

@@ -174,7 +174,10 @@ function DataBrowserTab({ isDark = true, apiBasePath = '/api/admin/vibe', focusC
             });
             if (!response.ok) {
                 const errData = await response.json().catch(() => ({}));
-                throw new Error(errData.error?.message || 'Delete failed');
+                // PAY-1425: the handler returns a fixed message plus a correlationId (never upstream
+                // text). Surface the id so an admin can quote it to an operator.
+                const ref = errData.error?.correlationId ? ` (ref ${errData.error.correlationId})` : '';
+                throw new Error(`${errData.error?.message || 'Delete failed'}${ref}`);
             }
             setSuccess(`Record ${id} deleted`);
             setTimeout(() => setSuccess(null), 3000);

package/dist/components/admin/SessionsTab.js

@@ -7,6 +7,12 @@ const react_1 = require("react");
 // -----------------------------------------------------------------------------
 // COMPONENT
 // -----------------------------------------------------------------------------
+// PAY-1429: admin handlers return a fixed message plus a correlationId (never upstream or
+// exception text). Surface the id so an admin can quote it to an operator.
+function errorWithRef(data, fallback) {
+    const msg = typeof data?.error === 'string' ? data.error : fallback;
+    return data?.correlationId ? `${msg} (ref ${data.correlationId})` : msg;
+}
 function SessionsTab({ isDark = true, apiBasePath = '/api/admin/sessions' }) {
     const [sessions, setSessions] = (0, react_1.useState)([]);
     const [isLoading, setIsLoading] = (0, react_1.useState)(false);
@@ -41,7 +47,7 @@ function SessionsTab({ isDark = true, apiBasePath = '/api/admin/sessions' }) {
                 setLastRefresh(new Date());
             }
             else {
-                setError(data.error || 'Failed to fetch sessions');
+                setError(errorWithRef(data, 'Failed to fetch sessions'));
             }
         }
         catch (err) {
@@ -91,7 +97,7 @@ function SessionsTab({ isDark = true, apiBasePath = '/api/admin/sessions' }) {
                 await fetchStats();
             }
             else {
-                alert(data.error || 'Failed to revoke session');
+                alert(errorWithRef(data, 'Failed to revoke session'));
             }
         }
         catch (err) {
@@ -120,7 +126,7 @@ function SessionsTab({ isDark = true, apiBasePath = '/api/admin/sessions' }) {
                 await fetchStats();
             }
             else {
-                alert(data.error || 'Failed to revoke sessions');
+                alert(errorWithRef(data, 'Failed to revoke sessions'));
             }
         }
         catch (err) {

package/dist/components/recovery/RequestedStep.d.ts

@@ -0,0 +1,11 @@
+interface Props {
+    onGoToLogin: () => void;
+}
+/**
+ * PAY-1588 (rigpert 60711): what a caller sees when the recovery request produced NO recovery session - an unknown
+ * address, a locked account, a throttled caller. ONE sentence, identical for all of them, so the screen cannot be used
+ * to tell which. It must not claim a reset happened (that is CompleteStep, reached only after a successful reset) and it
+ * must not name a cause.
+ */
+export declare function RequestedStep({ onGoToLogin }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/recovery/RequestedStep.js

@@ -0,0 +1,14 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestedStep = RequestedStep;
+const jsx_runtime_1 = require("react/jsx-runtime");
+/**
+ * PAY-1588 (rigpert 60711): what a caller sees when the recovery request produced NO recovery session - an unknown
+ * address, a locked account, a throttled caller. ONE sentence, identical for all of them, so the screen cannot be used
+ * to tell which. It must not claim a reset happened (that is CompleteStep, reached only after a successful reset) and it
+ * must not name a cause.
+ */
+function RequestedStep({ onGoToLogin }) {
+    return ((0, jsx_runtime_1.jsxs)("div", { className: "bg-white border border-gray-300 rounded p-8 text-center", children: [(0, jsx_runtime_1.jsx)("h2", { className: "text-2xl font-semibold text-gray-900 mb-2", children: "Check your email" }), (0, jsx_runtime_1.jsx)("p", { className: "text-gray-600 mb-6", children: "If an account exists for that email, we've sent instructions to reset your password." }), (0, jsx_runtime_1.jsx)("button", { onClick: onGoToLogin, className: "w-full py-2 px-4 border border-gray-300 rounded text-gray-900 font-medium hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-gray-400", children: "Back to sign in" })] }));
+}

package/dist/components/recovery/SetPasswordStep.js

@@ -4,17 +4,26 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SetPasswordStep = SetPasswordStep;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
+const usePasswordValidation_1 = require("../../hooks/usePasswordValidation");
+const password_rules_1 = require("../../lib/password-rules");
 function SetPasswordStep({ onSubmit, loading }) {
     const [password, setPassword] = (0, react_1.useState)('');
     const [confirmPassword, setConfirmPassword] = (0, react_1.useState)('');
     const [showPassword, setShowPassword] = (0, react_1.useState)(false);
     const [showConfirmPassword, setShowConfirmPassword] = (0, react_1.useState)(false);
     const passwordsMatch = password === confirmPassword && password !== '';
+    // PAY-1591: ADVISORY only. It shows the rules and what is missing; it never disables submit, because the validator
+    // may be down and the IdP is the authority (a dead validator must not trap a user who already spent their code).
+    const { setPassword: validateAsYouType, policy, failedRequirements } = (0, usePasswordValidation_1.usePasswordValidation)();
+    // The policy only comes back with a validation, so ask once on mount with a one-character probe (it never leaves the
+    // policy question; the answer is what the rules line is built from). Until it lands the line says the rules are coming.
+    (0, react_1.useEffect)(() => { validateAsYouType('a'); }, [validateAsYouType]);
+    const missing = failedRequirements.filter((r) => !/^(Unable to validate|Password validation)/i.test(r));
     const handleSubmit = (e) => {
         e.preventDefault();
         if (passwordsMatch) {
             onSubmit(password, confirmPassword);
         }
     };
-    return ((0, jsx_runtime_1.jsxs)("div", { className: "bg-white border border-gray-300 rounded p-8", children: [(0, jsx_runtime_1.jsx)("h2", { className: "text-xl font-semibold text-gray-900 mb-2", children: "Set New Password" }), (0, jsx_runtime_1.jsx)("p", { className: "text-sm text-gray-600 mb-6", children: "Choose a strong password for your account." }), (0, jsx_runtime_1.jsxs)("form", { onSubmit: handleSubmit, className: "space-y-4", children: [(0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("label", { htmlFor: "password", className: "block text-sm font-medium text-gray-900 mb-1", children: "New Password" }), (0, jsx_runtime_1.jsxs)("div", { className: "relative", children: [(0, jsx_runtime_1.jsx)("input", { type: showPassword ? 'text' : 'password', id: "password", value: password, onChange: (e) => setPassword(e.target.value), required: true, disabled: loading, className: "w-full px-3 py-2 border border-gray-300 rounded focus:ring-2 focus:ring-gray-900 focus:outline-none disabled:opacity-50 disabled:bg-gray-50 pr-10" }), (0, jsx_runtime_1.jsx)("button", { type: "button", onClick: () => setShowPassword(!showPassword), className: "absolute right-2 top-1/2 -translate-y-1/2 text-gray-600 hover:text-gray-900", children: showPassword ? '👁️' : '👁️‍🗨️' })] })] }), (0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("label", { htmlFor: "confirmPassword", className: "block text-sm font-medium text-gray-900 mb-1", children: "Confirm New Password" }), (0, jsx_runtime_1.jsxs)("div", { className: "relative", children: [(0, jsx_runtime_1.jsx)("input", { type: showConfirmPassword ? 'text' : 'password', id: "confirmPassword", value: confirmPassword, onChange: (e) => setConfirmPassword(e.target.value), required: true, disabled: loading, className: "w-full px-3 py-2 border border-gray-300 rounded focus:ring-2 focus:ring-gray-900 focus:outline-none disabled:opacity-50 disabled:bg-gray-50 pr-10" }), (0, jsx_runtime_1.jsx)("button", { type: "button", onClick: () => setShowConfirmPassword(!showConfirmPassword), className: "absolute right-2 top-1/2 -translate-y-1/2 text-gray-600 hover:text-gray-900", children: showConfirmPassword ? '👁️' : '👁️‍🗨️' })] })] }), !passwordsMatch && confirmPassword && ((0, jsx_runtime_1.jsx)("div", { className: "bg-red-50 border border-red-200 rounded p-3", children: (0, jsx_runtime_1.jsx)("p", { className: "text-red-700 text-sm", children: "Passwords do not match" }) })), (0, jsx_runtime_1.jsx)("button", { type: "submit", disabled: !passwordsMatch || loading, className: "w-full py-2 px-4 border border-gray-300 rounded text-gray-900 font-medium hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-gray-900 disabled:opacity-50 disabled:cursor-not-allowed", children: loading ? 'Resetting Password...' : 'Reset Password' })] })] }));
+    return ((0, jsx_runtime_1.jsxs)("div", { className: "bg-white border border-gray-300 rounded p-8", children: [(0, jsx_runtime_1.jsx)("h2", { className: "text-xl font-semibold text-gray-900 mb-2", children: "Set New Password" }), (0, jsx_runtime_1.jsx)("p", { className: "text-sm text-gray-600 mb-2", children: "Choose a strong password for your account." }), (0, jsx_runtime_1.jsx)("p", { "data-testid": "password-rules", className: "text-sm text-gray-700 mb-6", children: (0, password_rules_1.passwordRulesText)(policy) }), (0, jsx_runtime_1.jsxs)("form", { onSubmit: handleSubmit, className: "space-y-4", children: [(0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("label", { htmlFor: "password", className: "block text-sm font-medium text-gray-900 mb-1", children: "New Password" }), (0, jsx_runtime_1.jsxs)("div", { className: "relative", children: [(0, jsx_runtime_1.jsx)("input", { type: showPassword ? 'text' : 'password', id: "password", value: password, onChange: (e) => { setPassword(e.target.value); validateAsYouType(e.target.value); }, required: true, disabled: loading, className: "w-full px-3 py-2 border border-gray-300 rounded focus:ring-2 focus:ring-gray-900 focus:outline-none disabled:opacity-50 disabled:bg-gray-50 pr-10" }), (0, jsx_runtime_1.jsx)("button", { type: "button", onClick: () => setShowPassword(!showPassword), className: "absolute right-2 top-1/2 -translate-y-1/2 text-gray-600 hover:text-gray-900", children: showPassword ? '👁️' : '👁️‍🗨️' })] })] }), (0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("label", { htmlFor: "confirmPassword", className: "block text-sm font-medium text-gray-900 mb-1", children: "Confirm New Password" }), (0, jsx_runtime_1.jsxs)("div", { className: "relative", children: [(0, jsx_runtime_1.jsx)("input", { type: showConfirmPassword ? 'text' : 'password', id: "confirmPassword", value: confirmPassword, onChange: (e) => setConfirmPassword(e.target.value), required: true, disabled: loading, className: "w-full px-3 py-2 border border-gray-300 rounded focus:ring-2 focus:ring-gray-900 focus:outline-none disabled:opacity-50 disabled:bg-gray-50 pr-10" }), (0, jsx_runtime_1.jsx)("button", { type: "button", onClick: () => setShowConfirmPassword(!showConfirmPassword), className: "absolute right-2 top-1/2 -translate-y-1/2 text-gray-600 hover:text-gray-900", children: showConfirmPassword ? '👁️' : '👁️‍🗨️' })] })] }), password && missing.length > 0 && ((0, jsx_runtime_1.jsx)("ul", { "data-testid": "password-missing", className: "text-sm text-gray-700 list-disc pl-5", children: missing.map((r) => ((0, jsx_runtime_1.jsx)("li", { children: r }, r))) })), !passwordsMatch && confirmPassword && ((0, jsx_runtime_1.jsx)("div", { className: "bg-red-50 border border-red-200 rounded p-3", children: (0, jsx_runtime_1.jsx)("p", { className: "text-red-700 text-sm", children: "Passwords do not match" }) })), (0, jsx_runtime_1.jsx)("button", { type: "submit", disabled: !passwordsMatch || loading, className: "w-full py-2 px-4 border border-gray-300 rounded text-gray-900 font-medium hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-gray-900 disabled:opacity-50 disabled:cursor-not-allowed", children: loading ? 'Resetting Password...' : 'Reset Password' })] })] }));
 }

package/dist/config/env.d.ts

@@ -19,8 +19,6 @@ export declare const API_ENDPOINTS: {
         readonly profile: "/api/account/profile";
         readonly updateProfile: "/api/account/profile";
         readonly maskedInfo: "/api/account/masked-info";
-        readonly sendResetCode: "/api/account/send-reset-code";
-        readonly verifyResetCode: "/api/account/verify-reset-code";
         readonly resetPassword: "/api/account/reset-password";
         readonly changePassword: "/api/account/change-password";
         readonly validatePassword: "/api/account/validate-password";

package/dist/config/env.js

@@ -29,8 +29,6 @@ exports.API_ENDPOINTS = {
         profile: '/api/account/profile',
         updateProfile: '/api/account/profile',
         maskedInfo: '/api/account/masked-info',
-        sendResetCode: '/api/account/send-reset-code',
-        verifyResetCode: '/api/account/verify-reset-code',
         resetPassword: '/api/account/reset-password',
         changePassword: '/api/account/change-password',
         validatePassword: '/api/account/validate-password'

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { AuthProvider, useAuthConfig, useAuthMode, useFederatedProviders, useFed
 export type { AuthConfig } from './types/auth';
 export { makeAuthDecision } from './auth/auth-decision';
 export { isUnauthenticatedRoute, configurePublicRoutes, getRouteConfig } from './auth/route-config';
+export { safeCallbackPath, isSafeCallbackPath, resolveCallbackDestination, DEFAULT_CALLBACK } from './auth/safe-callback';
 export { createMvpMiddleware } from './middleware/create-middleware';
 export { UserAvatarMenu, MobileNavDrawer } from './components/account';
 export type { UserAvatarMenuProps, MobileNavDrawerProps, NavItem, NavSection } from './components/account';

package/dist/index.js

@@ -8,7 +8,7 @@
 // - Better Auth: import { createBetterAuthInstance } from '@payez/next-mvp/auth/better-auth'
 // - Server auth: import { getSession } from '@payez/next-mvp/server/auth'
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.queryAuditLog = exports.writeAuditLog = exports.getHealthMetrics = exports.getErrorMetrics = exports.useAdminAnalytics = exports.useAuditLog = exports.useHealthMetrics = exports.useErrorMetrics = exports.AdminAnalyticsLayout = exports.AuditLogViewer = exports.HealthMetricsCard = exports.ErrorMetricsCard = exports.MobileNavDrawer = exports.UserAvatarMenu = exports.createMvpMiddleware = exports.getRouteConfig = exports.configurePublicRoutes = exports.isUnauthenticatedRoute = exports.makeAuthDecision = exports.useTraditionalAuthEnabled = exports.useFederatedAuthEnabled = exports.useFederatedProviders = exports.useAuthMode = exports.useAuthConfig = exports.AuthProvider = exports.useAnonSession = exports.fetchWithAuth = void 0;
+exports.queryAuditLog = exports.writeAuditLog = exports.getHealthMetrics = exports.getErrorMetrics = exports.useAdminAnalytics = exports.useAuditLog = exports.useHealthMetrics = exports.useErrorMetrics = exports.AdminAnalyticsLayout = exports.AuditLogViewer = exports.HealthMetricsCard = exports.ErrorMetricsCard = exports.MobileNavDrawer = exports.UserAvatarMenu = exports.createMvpMiddleware = exports.DEFAULT_CALLBACK = exports.resolveCallbackDestination = exports.isSafeCallbackPath = exports.safeCallbackPath = exports.getRouteConfig = exports.configurePublicRoutes = exports.isUnauthenticatedRoute = exports.makeAuthDecision = exports.useTraditionalAuthEnabled = exports.useFederatedAuthEnabled = exports.useFederatedProviders = exports.useAuthMode = exports.useAuthConfig = exports.AuthProvider = exports.useAnonSession = exports.fetchWithAuth = void 0;
 // Client-safe exports only
 // Client-side utilities
 var fetch_with_auth_1 = require("./client/fetch-with-auth");
@@ -31,6 +31,13 @@ var route_config_1 = require("./auth/route-config");
 Object.defineProperty(exports, "isUnauthenticatedRoute", { enumerable: true, get: function () { return route_config_1.isUnauthenticatedRoute; } });
 Object.defineProperty(exports, "configurePublicRoutes", { enumerable: true, get: function () { return route_config_1.configurePublicRoutes; } });
 Object.defineProperty(exports, "getRouteConfig", { enumerable: true, get: function () { return route_config_1.getRouteConfig; } });
+// The ONE callback-target guard (N7 / PAY-1989): apps import this instead of
+// copying it. Exposed from the main index AND as the subpath ./auth/safe-callback.
+var safe_callback_1 = require("./auth/safe-callback");
+Object.defineProperty(exports, "safeCallbackPath", { enumerable: true, get: function () { return safe_callback_1.safeCallbackPath; } });
+Object.defineProperty(exports, "isSafeCallbackPath", { enumerable: true, get: function () { return safe_callback_1.isSafeCallbackPath; } });
+Object.defineProperty(exports, "resolveCallbackDestination", { enumerable: true, get: function () { return safe_callback_1.resolveCallbackDestination; } });
+Object.defineProperty(exports, "DEFAULT_CALLBACK", { enumerable: true, get: function () { return safe_callback_1.DEFAULT_CALLBACK; } });
 var create_middleware_1 = require("./middleware/create-middleware");
 Object.defineProperty(exports, "createMvpMiddleware", { enumerable: true, get: function () { return create_middleware_1.createMvpMiddleware; } });
 // Account Components

package/dist/lib/app-slug.d.ts

@@ -14,6 +14,27 @@
  * Caches the result for performance.
  */
 export declare function getAppSlug(): string;
+/**
+ * The session cookie name has TWO producers: better-auth mints `${idpConfig.clientSlug || getAppSlug()}.session-token`, while
+ * the gate and every reader use getSessionCookieName() = getAppSlug() = APP_SLUG || CLIENT_ID. When the IdP's slug is known and
+ * differs, the gate looks for a cookie that was never set and every better-auth (Google) session bounces to
+ * /sign-in?error=SessionInvalid straight after a successful 2FA (rigpert 60743, live on :4797 with CLIENT_ID=idp-admin-ui-graft
+ * against clientSlug idp_admin_ui_graft). FAIL CLOSED: refuse rather than run with two names. No IdP slug -> nothing to compare.
+ */
+export declare function slugMismatchReason(idpClientSlug: string | null | undefined): string | null;
+/**
+ * rigpert 60813: when the IdP returns NO client slug for this app (an unknown client: the config fetch failed or came back
+ * without one), startup must fail LOUD. Silently defaulting would run with a cookie name nobody verified against the IdP. The
+ * startup path swallows a failed config fetch when BETTER_AUTH_SECRET is supplied by env, so without this an unregistered
+ * CLIENT_ID (e.g. payez_idp_customer_web, absent on dev-93) would boot 'fine'.
+ */
+export declare function assertIdpSlugKnown(idpClientSlug: string | null | undefined): void;
+/**
+ * The health-endpoint view: a mismatch is always reportable; an UNKNOWN slug is reported only once startup has actually been
+ * attempted (before that nothing is known yet and health must not go red on a pod that has not started initialising).
+ */
+export declare function slugStateReason(idpClientSlug: string | null | undefined, startupAttempted: boolean): string | null;
+export declare function assertAppSlugMatchesIdp(idpClientSlug: string | null | undefined): void;
 /**
  * Clears the cached slug (useful for testing).
  */

package/dist/lib/app-slug.js

@@ -12,6 +12,10 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getAppSlug = getAppSlug;
+exports.slugMismatchReason = slugMismatchReason;
+exports.assertIdpSlugKnown = assertIdpSlugKnown;
+exports.slugStateReason = slugStateReason;
+exports.assertAppSlugMatchesIdp = assertAppSlugMatchesIdp;
 exports.clearSlugCache = clearSlugCache;
 exports.getSessionPrefix = getSessionPrefix;
 exports.getAnonPrefix = getAnonPrefix;
@@ -37,6 +41,53 @@ function getAppSlug() {
     cachedSlug = process.env.APP_SLUG || process.env.CLIENT_ID || 'payez';
     return cachedSlug;
 }
+/**
+ * The session cookie name has TWO producers: better-auth mints `${idpConfig.clientSlug || getAppSlug()}.session-token`, while
+ * the gate and every reader use getSessionCookieName() = getAppSlug() = APP_SLUG || CLIENT_ID. When the IdP's slug is known and
+ * differs, the gate looks for a cookie that was never set and every better-auth (Google) session bounces to
+ * /sign-in?error=SessionInvalid straight after a successful 2FA (rigpert 60743, live on :4797 with CLIENT_ID=idp-admin-ui-graft
+ * against clientSlug idp_admin_ui_graft). FAIL CLOSED: refuse rather than run with two names. No IdP slug -> nothing to compare.
+ */
+function slugMismatchReason(idpClientSlug) {
+    if (!idpClientSlug)
+        return null;
+    const gateSlug = getAppSlug();
+    return idpClientSlug !== gateSlug ? `SLUG_MISMATCH: cookie=${idpClientSlug} gate=${gateSlug}` : null;
+}
+/**
+ * rigpert 60813: when the IdP returns NO client slug for this app (an unknown client: the config fetch failed or came back
+ * without one), startup must fail LOUD. Silently defaulting would run with a cookie name nobody verified against the IdP. The
+ * startup path swallows a failed config fetch when BETTER_AUTH_SECRET is supplied by env, so without this an unregistered
+ * CLIENT_ID (e.g. payez_idp_customer_web, absent on dev-93) would boot 'fine'.
+ */
+function assertIdpSlugKnown(idpClientSlug) {
+    if (idpClientSlug)
+        return;
+    throw new Error(`[FATAL] The IdP returned no client slug for this app (gate slug "${getAppSlug()}"). Either CLIENT_ID/APP_SLUG names a client ` +
+        `the IdP does not know, or its config could not be fetched. Refusing to start with an unverified session cookie name.`);
+}
+/**
+ * The health-endpoint view: a mismatch is always reportable; an UNKNOWN slug is reported only once startup has actually been
+ * attempted (before that nothing is known yet and health must not go red on a pod that has not started initialising).
+ */
+function slugStateReason(idpClientSlug, startupAttempted) {
+    const mismatch = slugMismatchReason(idpClientSlug);
+    if (mismatch)
+        return mismatch;
+    if (startupAttempted && !idpClientSlug)
+        return `SLUG_UNKNOWN: the IdP returned no client slug for this app gate=${getAppSlug()}`;
+    return null;
+}
+function assertAppSlugMatchesIdp(idpClientSlug) {
+    if (!idpClientSlug)
+        return;
+    const gateSlug = getAppSlug();
+    if (slugMismatchReason(idpClientSlug) !== null) {
+        throw new Error(`[FATAL] Session cookie name would have two sources: the IdP client slug is "${idpClientSlug}" but this app's slug ` +
+            `(APP_SLUG, else CLIENT_ID) is "${gateSlug}". better-auth would set "${idpClientSlug}.session-token" while the gate reads ` +
+            `"${gateSlug}.session-token", so every better-auth session would be rejected. Set APP_SLUG (or CLIENT_ID) to "${idpClientSlug}".`);
+    }
+}
 /**
  * Clears the cached slug (useful for testing).
  */

package/dist/lib/ensure-fresh-access-token.d.ts

@@ -17,6 +17,32 @@ export type EnsureFreshResult = {
     accessTokenExpires: number;
     /** True if we refreshed (or a concurrent refresh completed); false if the stored token was already fresh. */
     refreshed: boolean;
+    /**
+     * CARD 320072. Is the token in THIS result actually in the session store?
+     *
+     * ON THIS BRANCH OF THE UNION IT IS ALWAYS `true`, AND THAT IS THE POINT.
+     * Every `ok: true` return either read the token back from the store or
+     * wrote it and confirmed the write. An unpersisted refresh does not reach
+     * an `ok: true` result at all — it returns `ok:false, SESSION_PERSIST_FAILED`
+     * from the other branch below.
+     *
+     * READ THIS BEFORE YOU DELETE THE FIELD. It is declared `boolean` rather
+     * than the literal `true` on purpose: it is the assertable witness that the
+     * escalation is still wired. If someone later re-weakens the persist site
+     * back to reporting success, this field is where that regression becomes
+     * visible to a test instead of invisible to everyone. Cases 2 and 7 in
+     * test/ensure-fresh-persist-failure.test.cjs assert on it.
+     *
+     * WHAT THIS COMMENT USED TO SAY, AND WHY IT IS GONE. It documented `false`
+     * as a live value on an ok:true result — "we hold a valid token that was
+     * not persisted" — because that WAS the contract before this merge, when
+     * the dropped write was reported as a success with a flag on it. Blending
+     * in the escalation made that sentence describe a state the code can no
+     * longer produce. A docblock asserting an impossible semantic is exactly
+     * the defect f5ac6dc3 was written to fix, one file over; reproducing it
+     * here while merging that fix would be absurd.
+     */
+    persisted: boolean;
 } | {
     ok: false;
     code: string;

package/dist/lib/ensure-fresh-access-token.js

@@ -66,7 +66,8 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
     const effectiveExpires = jwtExpires > 0 ? Math.min(redisExpires || jwtExpires, jwtExpires) : redisExpires;
     const msUntilExpiry = effectiveExpires - now;
     if (msUntilExpiry > safetyWindowMs) {
-        return { ok: true, accessToken: storedToken, accessTokenExpires: effectiveExpires, refreshed: false };
+        // Durable by construction: this token came OUT of the store and we wrote nothing.
+        return { ok: true, accessToken: storedToken, accessTokenExpires: effectiveExpires, refreshed: false, persisted: true };
     }
     if (!session.idpRefreshToken) {
         return {
@@ -103,6 +104,8 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
                                 accessToken: after.idpAccessToken,
                                 accessTokenExpires: after.idpAccessTokenExpires,
                                 refreshed: true,
+                                // Read back from the store after the winner's refresh - durable.
+                                persisted: true,
                             };
                         }
                     }
@@ -140,6 +143,8 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
                     accessToken: latest.idpAccessToken,
                     accessTokenExpires: latest.idpAccessTokenExpires,
                     refreshed: true,
+                    // Post-lock re-read: another caller already refreshed and stored this.
+                    persisted: true,
                 };
             }
         }
@@ -229,12 +234,37 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
                 // between pre-lock read and our send would be misjudged.
                 const tokenUnchanged = !!sentRefreshToken && postRefresh?.idpRefreshToken === sentRefreshToken;
                 if (tokenUnchanged) {
-                    await (0, session_store_1.updateSession)(sessionToken, {
+                    /**
+                     * 320072: this is the OTHER updateSession call in this file, and it
+                     * does NOT escalate on a null return the way the persist site below
+                     * does. Checked, not overlooked: reaching here requires
+                     * `tokenUnchanged`, which requires `postRefresh?.idpRefreshToken` to
+                     * equal the token we sent — so the CAS read three lines up already
+                     * proved the row exists. A missing row makes tokenUnchanged false and
+                     * routes to the else branch instead, so the dropped-write path is
+                     * very nearly unreachable here.
+                     *
+                     * "Very nearly" is why the return IS still captured. The residual both
+                     * halves of this merge identified is real: the row can expire between
+                     * that CAS read and this write, in which case the dead refresh token is
+                     * NOT cleared and the "we discarded it" claim in the error below is
+                     * false. That costs nothing to observe and cannot be inferred from any
+                     * other line, so it is warned rather than assumed — see `if (!cleared)`
+                     * immediately below. The RESULT is unchanged either way: the session is
+                     * unusable and we return the same non-ok payload.
+                     */
+                    const cleared = await (0, session_store_1.updateSession)(sessionToken, {
                         idpRefreshToken: '',
                         idpRefreshTokenExpires: undefined,
                         refreshTokenClearedAt: Date.now(),
                         refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${code}`,
                     });
+                    if (!cleared) {
+                        console.warn('[ENSURE-FRESH] discard-token clear did not persist - no canonical session row', {
+                            code,
+                            requestId,
+                        });
+                    }
                 }
                 else {
                     // Concurrent refresh already rotated the token — our 401 is stale. Return the
@@ -247,6 +277,8 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
                             accessToken: postRefresh.idpAccessToken,
                             accessTokenExpires: postRefresh.idpAccessTokenExpires,
                             refreshed: true,
+                            // `postRefresh` is a store read, so this token is by definition stored.
+                            persisted: true,
                         };
                     }
                 }
@@ -301,7 +333,14 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
         const acrLevel = String(decoded?.acr || session.authenticationLevel || '1');
         const hasNewRefresh = typeof newRefresh === 'string' && newRefresh.length > 0;
         const newKid = (0, token_utils_1.extractKidFromToken)(newAccess);
-        await (0, session_store_1.updateSession)(sessionToken, {
+        // *** CARD 320072. CAPTURE THIS RETURN. ***
+        // `updateSession` returns null - and writes nothing - when the canonical
+        // session row is missing, which happens whenever the BA fallback above is what
+        // resolved this session. Discarding the return is what let this function
+        // report `ok:true, refreshed:true` for a refresh it had just thrown away.
+        // The full rationale for what we DO about it is at the `if (!persisted)`
+        // block below; this line only makes the answer available.
+        const persisted = await (0, session_store_1.updateSession)(sessionToken, {
             ...session,
             idpAccessToken: newAccess,
             idpAccessTokenExpires: accessTokenExpires,
@@ -320,7 +359,69 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
             mfaExpiresAt: decoded?.mfa_expires ? parseInt(decoded.mfa_expires) * 1000 : session.mfaExpiresAt,
             mfaValidityHours: decoded?.mfa_validity_hours ? parseInt(decoded.mfa_validity_hours) : session.mfaValidityHours,
         });
-        return { ok: true, accessToken: newAccess, accessTokenExpires, refreshed: true };
+        /**
+         * 320072: DO NOT REPORT SUCCESS FOR A WRITE THAT WAS DISCARDED.
+         *
+         * `updateSession` returns null when the canonical session row is absent,
+         * which silently throws away EVERYTHING above — the new access token, the
+         * rotated refresh token, decodedAccessToken, authenticationMethods,
+         * mfaVerified, mfaCompletedAt, mfaExpiresAt. This return value was
+         * previously ignored, and the line below then reported
+         * `ok: true, refreshed: true`.
+         *
+         * WHY THAT IS WORSE THAN A PLAIN LOST WRITE. By this point the exchange at
+         * the IDP has ALREADY HAPPENED, so if refresh tokens are single-use the
+         * token we sent is now spent and its replacement is the thing we just
+         * dropped. The stored credential is therefore dead, and every later attempt
+         * re-sends that same dead token and fails. The user is bounced to LOGIN —
+         * not to verify-code — with nothing in the logs naming the cause.
+         *
+         * It did not even surface as a wrong answer to our one caller: server/auth.ts
+         * calls getRedisSession immediately after us, which is this same `getSession`,
+         * so it finds the same missing row and returns a generic NO_SESSION one frame
+         * later. The false `ok: true` was thus invisible AND the real cause — a
+         * dropped persist — was reported as an unrelated missing session.
+         *
+         * Naming it here is the point: the failure is reported at its true cause,
+         * with a code that says the refresh succeeded and the PERSIST is what
+         * failed. Not retryable — retrying burns another refresh token the same way.
+         *
+         * This is the card's option (b), deliberately. Option (a) — teaching
+         * updateSession to write through to whichever store holds the session,
+         * mirroring the read fallback above — is the better end state but changes
+         * write-path storage semantics for every caller, which is not this card.
+         *
+         * AND IT IS ALSO LOGGED, WHICH IS NOT THE SAME THING (BAPert R1134 §7,
+         * re-affirmed in R1145 §2c). Returning a named code tells the CALLER. §7
+         * requires that `persisted:false` reach a log A HUMAN READS, because the one
+         * caller — server/auth.ts — converts every non-ok result into the same
+         * generic 401 and keeps no record of which code produced it. Without this
+         * line the distinction we just bought at the type level is erased one frame
+         * later and no operator ever sees the word PERSIST. The escalation is the
+         * contract; the warn is the evidence.
+         */
+        if (!persisted) {
+            console.warn('[ENSURE-FRESH] refresh succeeded but was NOT persisted - no canonical session row', {
+                requestId,
+                refreshTokenRotated: hasNewRefresh,
+                persisted: false,
+            });
+            return {
+                ok: false,
+                code: 'SESSION_PERSIST_FAILED',
+                message: 'Token refresh succeeded at the IDP but the session could not be persisted; the rotated tokens were discarded.',
+                status: 401,
+                terminal: true,
+                retryable: false,
+                discardToken: true,
+                resolution: 'REAUTHENTICATE',
+            };
+        }
+        // `persisted: true` is not decoration and not a leftover: the `if` above is
+        // the only way out for a dropped write, so by construction anything reaching
+        // this line WAS written. Keeping the field keeps the ok:true branch of
+        // EnsureFreshResult total (Cases 2 and 7 assert on it) — BAPert R1145 §2d.
+        return { ok: true, accessToken: newAccess, accessTokenExpires, refreshed: true, persisted: true };
     }
     finally {
         if (weHoldLock) {

package/dist/lib/idp-client-config.d.ts

@@ -81,6 +81,26 @@ export interface IDPClientConfig {
     branding: BrandingConfig;
     baseClientUrl?: string;
 }
+/**
+ * The IdP serves the signing secret and every OAuth provider client secret in the client config, to any
+ * caller holding a client assertion (PAY-1460). It cannot stop serving them while this package depends on
+ * them: every earlier version throws FATAL on an empty config authSecret, whatever the environment says.
+ *
+ * So both are now resolved ENV FIRST, config second:
+ *   signing secret   BETTER_AUTH_SECRET (canonical), NEXTAUTH_SECRET (legacy alias), then config authSecret.
+ *                    Uses the module-load snapshot above: this module publishes the config value into
+ *                    process.env, so a live read would mistake the IdP's value for the operator's.
+ *   provider secret  <PROVIDER>_CLIENT_SECRET, provider name upper-cased with non-alphanumerics as '_'
+ *                    (GOOGLE_CLIENT_SECRET, APPLE_CLIENT_SECRET, MICROSOFT_CLIENT_SECRET), then config.
+ *
+ * The FATAL on an empty signing secret is unchanged and still load-bearing: it now fires only when BOTH the
+ * environment and the config are empty.
+ *
+ * Values are never logged. The SOURCE of each is logged once per change. An env-sourced value is never
+ * written to the Redis config cache (stripEnvSecrets); a cache read re-applies the environment.
+ */
+export type SecretSource = string;
+export declare function providerSecretEnvVar(provider: string): string;
 /**
  * Get IDP client configuration with multi-tier caching.
  *