@payez/next-mvp 4.4.7 → 4.4.9

package/src/auth/better-auth.ts

@@ -281,19 +281,42 @@ export function buildBetterAuthProviders(
       clientSecret: oauth.clientSecret,
       scope: wireScopes.length > 0 ? wireScopes : undefined,
       /**
-       * 260419 — CLOSE THE SECOND SELF-SERVE PROVISIONING DOOR. 259805 gated
-       * the signup BFF on allow_public_registration, but the social lane never
-       * touches that code: better-auth creates the user through its own
-       * internalAdapter at the OAuth callback, and its ONLY guard is this flag.
+       * PAY-2005 — DISABLE-SIGN-UP IS REMOVED, DELIBERATELY. DO NOT RE-ADD IT.
        *
-       * Wired from the tenant's own policy, explicit-true-opens: the IDP config
-       * keeps allowPublicRegistration UNDEFINED when the tenant never answered
-       * (idp-client-config.ts, the no-fabricated-default rule), and an
-       * unanswered policy question must not provision accounts. That matches
-       * the FE's silent-default-is-decline posture for the "Create account"
-       * affordance. A tenant that wants Google self-serve says so.
+       * 260419 wired this from `config.authSettings?.allowPublicRegistration` to
+       * close a client-side self-serve provisioning door. It cannot do that job
+       * correctly, and it BREAKS SIGN-IN:
+       *
+       *   - This app runs better-auth in STATELESS mode (no DB adapter — see the
+       *     file header). better-auth therefore has NO user store, so at the OAuth
+       *     callback it cannot tell an EXISTING user from a NEW one. Its
+       *     handleOAuthUserInfo consults `disableSignUp` for BOTH, so
+       *     `disableSignUp: true` refuses a returning user exactly like a
+       *     stranger. Measured live 2026-09-30 (PAY-2005): portal.keelauth.com
+       *     Google sign-in bounced to /sign-in with Better Auth `signup_disabled`
+       *     once client 12's allow_public_registration reported false.
+       *
+       *   - The REAL registration gate already exists and is correct, at the IDP:
+       *     PayEz.External.Id.Api ExternalAuthController.oauth-callback looks the
+       *     user up by verified email (:799); an existing user logs in UNTOUCHED
+       *     (:811); only the isNewUser branch (:853) calls INewUserRegistrar,
+       *     which refuses fail-closed when the client forbids public registration
+       *     (NewUserRegistrar.cs:65, `SecurityFlags.AllowPublicRegistration != true`).
+       *     Its own comment states the contract: "existing federated users ...
+       *     log in untouched, so gating here never blocks login."
+       *
+       * So this flag was a DUPLICATE gate that could only ever misfire — it cannot
+       * distinguish new from existing, and the IDP already refuses new identities.
+       * Removing it restores sign-in for existing users WITHOUT reopening
+       * self-serve: a NEW identity that completes the better-auth leg still gets
+       * REFUSED at the IDP exchange and never receives IDP tokens, which is the
+       * portal's actual authorization gate.
+       *
+       * WHERE "no self-serve sign-up" IS ENFORCED NOW: the IDP's NewUserRegistrar
+       * (above) as the backstop, and each app's own front-door sign-up gate
+       * (e.g. the portal's signup-gate.ts / SignUpCard) for the UI affordance.
+       * Both are correct and neither is this flag.
        */
-      disableSignUp: config.authSettings?.allowPublicRegistration !== true,
       // Google is overly eager to reuse the last account unless we
       // explicitly ask for account selection on each social login.
       prompt: typeof rawPrompt === 'string'
@@ -984,11 +1007,17 @@ export async function getBetterAuthHandler(): Promise<{ GET: (req: Request) => P
  * header of the response to find the BA Redis key.
  *
  * This replaces the old databaseHooks approach which doesn't fire in stateless mode.
+ *
+ * RETURNS the IdP's own error code on an IDP refusal, or null otherwise
+ * (PAY-2005 scenario (b), BAPert ruling 67897). It used to return a bare
+ * boolean, so `REGISTRATION_NOT_ALLOWED` was indistinguishable from a network
+ * blip and every cause collapsed to one generic login-page code — a NEW user
+ * refused registration bounced silently, which is the failure Jon named.
  */
 export async function exchangeOAuthForIdpTokens(
   sessionToken: string,
   provider: string = 'google'
-): Promise<boolean> {
+): Promise<boolean | string> {
   try {
     const config = await getIDPClientConfig();
     const appSlug = config.clientSlug || getAppSlug();
@@ -1081,6 +1110,36 @@ export async function exchangeOAuthForIdpTokens(
     if (!oauthRes.ok) {
       console.error('[BETTER_AUTH] IDP oauth-callback failed:', oauthRes.status);
 
+      /**
+       * PAY-2005 scenario (b) — RETURN THE IDP'S ERROR CODE (BAPert ruling 67897).
+       *
+       * Every refusal used to return a bare `false`, so the abort collapsed ALL
+       * causes to one generic `OAUTH_SIGN_IN_FAILED`: a NEW user refused
+       * registration (`REGISTRATION_NOT_ALLOWED`, ExternalAuthController.cs:908)
+       * bounced silently, indistinguishable from a network blip. Jon named the
+       * clear message explicitly (67856): "(b) a brand-new Google user with
+       * registration OFF is refused by the IDP with a clear message, not a
+       * silent bounce."
+       *
+       * The envelope is `{ error: { code, message } }` (PayEzControllerBase.Error).
+       * We read ONLY `error.code` and return it VERBATIM — the abort puts it in
+       * the `?error=` param, and the HOST's allowlist decides whether to render
+       * it. The package does NOT interpret the code and does NOT add a message
+       * (that would be a second allowlist). No code in the body -> null (the
+       * generic host code), exactly as before.
+       */
+      let idpErrorCode: string | null = null;
+      try {
+        const parsed = JSON.parse(oauthResText);
+        // FORWARD ONLY AN ALLOWLISTED CODE. Every other refusal keeps PAY-1733's single neutral code — an
+        // unlisted code would render nothing on the host page, which is the silent bounce this exists to end.
+        if (typeof parsed?.error?.code === 'string' && IDP_ERROR_CODES_TO_FORWARD.has(parsed.error.code)) {
+          idpErrorCode = parsed.error.code;
+        }
+      } catch {
+        /* non-JSON refusal body -> no code (generic abort) */
+      }
+
       /**
        * WHY THIS LOGS ONLY ON FAILURE, AND WHY IT LOGS THESE FIELDS.
        *
@@ -1128,7 +1187,7 @@ export async function exchangeOAuthForIdpTokens(
         sent_client_id: resolveClientKey(config, 'auth/better-auth:oauth-callback').key ?? null,
         idp_url: idpUrl,
       });
-      return false;
+      return idpErrorCode ?? false;
     }
 
     let idpData: any;
@@ -1138,6 +1197,7 @@ export async function exchangeOAuthForIdpTokens(
     if (!result?.access_token) {
       console.warn('[BETTER_AUTH] IDP oauth-callback returned no access_token. Keys:', Object.keys(result || {}));
       return false;
+
     }
 
     // Build IDP token data
@@ -1248,6 +1308,7 @@ export async function exchangeOAuthForIdpTokens(
     // Storage is shared with the passkey sign-in path — see storeIdpTokensInSession.
     const stored = await storeIdpTokensInSession(sessionToken, idpTokenData, provider);
     if (stored) console.log('[BETTER_AUTH] IDP tokens stored in session for', email);
+    // true = success (tokens stored). false = a non-IdP failure with no specific code (generic abort).
     return stored;
   } catch (err) {
     console.error('[BETTER_AUTH] IDP token exchange failed:', err instanceof Error ? err.message : String(err));
@@ -1255,6 +1316,7 @@ export async function exchangeOAuthForIdpTokens(
   }
 }
 
+
 /**
  * Write IDP tokens into an EXISTING Better Auth session. Storage only — this
  * function never acquires tokens and never decides who the caller is.
@@ -1351,6 +1413,19 @@ export async function storeIdpTokensInSession(
  */
 export const OAUTH_SIGN_IN_FAILED_ERROR = 'OAUTH_SIGN_IN_FAILED';
 
+/**
+ * The ONLY IdP refusal codes the package forwards to the login page (PAY-2005 (b), BAPert 67897).
+ *
+ * Default stays PAY-1733's ONE neutral code: the cause of an ordinary failed exchange lives in the server
+ * log, never on the page. A code is forwarded ONLY when it earns a distinct user-facing message — today just
+ * the registration refusal, so a NEW Google user with registration OFF sees a clear "not open to sign-up"
+ * line instead of a silent bounce. Adding a code here REQUIRES a matching entry in the host allowlist
+ * (portal: src/lib/auth/magic-link-outcome.ts); an unlisted code renders nothing, which is a silent bounce
+ * wearing a different number. Add them together, never one alone.
+ */
+export const IDP_ERROR_CODES_TO_FORWARD: ReadonlySet<string> = new Set(['REGISTRATION_NOT_ALLOWED']);
+
+
 /**
  * Re-emit each cookie the callback response SET as an immediate expiry, keeping the attributes that decide
  * WHICH cookie the browser overwrites (Path, Domain, Secure, SameSite, HttpOnly - a `__Secure-` name is only
@@ -1387,6 +1462,7 @@ async function abortOAuthSignIn(
   sessionToken: string | null,
   cookieHeader: string,
   loginPath: string,
+  errorCode: string = OAUTH_SIGN_IN_FAILED_ERROR,
 ): Promise<Response> {
   const headers = new Headers();
   if (sessionToken) {
@@ -1405,8 +1481,8 @@ async function abortOAuthSignIn(
     }
   }
   for (const sc of expireSetCookies(callbackResponse.headers.getSetCookie?.() ?? [])) headers.append('set-cookie', sc);
-  headers.set('location', `${loginPath}${loginPath.includes('?') ? '&' : '?'}error=${OAUTH_SIGN_IN_FAILED_ERROR}`);
-  console.warn('[BETTER_AUTH] OAuth sign-in ABORTED: the IdP exchange stored no tokens, so no session is kept (PAY-1733)', sessionToken ? tokenLogId(sessionToken) : '(no session)');
+  headers.set('location', `${loginPath}${loginPath.includes('?') ? '&' : '?'}error=${errorCode}`);
+  console.warn('[BETTER_AUTH] OAuth sign-in ABORTED: the IdP exchange stored no tokens, so no session is kept (PAY-1733)', sessionToken ? tokenLogId(sessionToken) : '(no session)', 'code=' + errorCode);
   return new Response(null, { status: 302, headers });
 }
 
@@ -1498,7 +1574,9 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
         .map((c: string) => c.split(';')[0])
         .join('; ');
       let sessionToken: string | null = null;
-      let exchanged = false;
+      // true = tokens stored; false = no specific IdP code (generic abort); a string = the IdP's own refusal code
+      // (PAY-2005 (b): REGISTRATION_NOT_ALLOWED, etc.), forwarded so the host can show a clear message.
+      let exchange: boolean | string = false;
       try {
         const auth = await getBetterAuthInstance();
         if (auth?.api?.getSession) {
@@ -1509,7 +1587,7 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
           if (session?.session?.token) {
             sessionToken = session.session.token;
             console.log('[BETTER_AUTH] Got session token from callback:', tokenLogId(session.session.token), '| email:', session.user?.email);
-            exchanged = await exchangeOAuthForIdpTokens(session.session.token);
+            exchange = await exchangeOAuthForIdpTokens(session.session.token);
           } else {
             console.warn('[BETTER_AUTH] Could not get session after OAuth callback');
           }
@@ -1517,7 +1595,11 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
       } catch (err: any) {
         console.error('[BETTER_AUTH] IDP token exchange failed:', err.message);
       }
-      if (!exchanged) return abortOAuthSignIn(response, sessionToken, cookieHeader, loginPath);
+      if (exchange !== true) {
+        // A specific IdP error code goes on the URL; otherwise the generic OAUTH_SIGN_IN_FAILED.
+        const errorCode = typeof exchange === 'string' ? exchange : OAUTH_SIGN_IN_FAILED_ERROR;
+        return abortOAuthSignIn(response, sessionToken, cookieHeader, loginPath, errorCode);
+      }
     }
 
     return response;

package/src/components/auth/FederatedAuthSection.tsx

@@ -9,12 +9,44 @@ interface Props {
   isLoading?: boolean;
 }
 
-const providerIcons: Record<FederatedProvider, { label: string; svg: React.ReactNode; color: string }> = {
+/**
+ * PAY-2104 — PER-PROVIDER BRAND TREATMENT, NOT ONE GENERIC BUTTON.
+ *
+ * Apple and Facebook both publish binding rules for their sign-in buttons and
+ * neither is satisfied by the generic "Continue with X" control this section
+ * used to render for every provider:
+ *   - APPLE (App Store Review Guidelines 4.8 / "Sign in with Apple" HIG): the
+ *     button MUST carry the Apple logo and one of Apple's own wordings. The
+ *     approved primary wording is "Sign in with Apple" ("Continue with Apple"
+ *     is the permitted alternative). "Continue with Apple" with no logo, which
+ *     is what the generic path produced, is non-compliant and is what App Store
+ *     review rejects. Black or white only.
+ *   - FACEBOOK (Meta Platform Terms / brand guidelines): "Continue with
+ *     Facebook", the Facebook "f" mark, and the brand blue (#1877F2) or white
+ *     are the sanctioned treatments.
+ * Google/Microsoft/GitHub keep the neutral control — they impose no such rule,
+ * and inventing brand colours for them would be a change nobody asked for.
+ *
+ * The mark inherits `currentColor` so it is legible on both the white neutral
+ * buttons and the black/blue branded ones without a second SVG per provider.
+ */
+const PROVIDER_BRAND: Record<
+  FederatedProvider,
+  { label: string; background: string; color: string; border: string }
+> = {
+  google: { label: 'Continue with Google', background: 'var(--bg-default, #ffffff)', color: 'var(--text-primary, #111827)', border: 'var(--border-default, #e5e7eb)' },
+  microsoft: { label: 'Continue with Microsoft', background: 'var(--bg-default, #ffffff)', color: 'var(--text-primary, #111827)', border: 'var(--border-default, #e5e7eb)' },
+  github: { label: 'Continue with GitHub', background: 'var(--bg-default, #ffffff)', color: 'var(--text-primary, #111827)', border: 'var(--border-default, #e5e7eb)' },
+  // Meta brand blue; white mark on blue, per the brand guidelines.
+  facebook: { label: 'Continue with Facebook', background: '#1877F2', color: '#ffffff', border: '#1877F2' },
+  // Apple HIG: black (or white) field, "Sign in with Apple", Apple logo.
+  apple: { label: 'Sign in with Apple', background: '#000000', color: '#ffffff', border: '#000000' },
+};
+
+const providerIcons: Record<FederatedProvider, { svg: React.ReactNode }> = {
   google: {
-    label: 'Google',
-    color: '#4285F4',
     svg: (
-      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor">
+      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
         <path d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z" fill="#4285F4"/>
         <path d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z" fill="#34A853"/>
         <path d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z" fill="#FBBC05"/>
@@ -23,10 +55,8 @@ const providerIcons: Record<FederatedProvider, { label: string; svg: React.React
     ),
   },
   microsoft: {
-    label: 'Microsoft',
-    color: '#0078D4',
     svg: (
-      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor">
+      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
         <rect x="1" y="1" width="9" height="9" fill="#F25022"/>
         <rect x="12" y="1" width="9" height="9" fill="#7FBA00"/>
         <rect x="1" y="12" width="9" height="9" fill="#00A4EF"/>
@@ -35,28 +65,25 @@ const providerIcons: Record<FederatedProvider, { label: string; svg: React.React
     ),
   },
   facebook: {
-    label: 'Facebook',
-    color: '#1877F2',
+    // currentColor: white on the Meta-blue button. A hardcoded #1877F2 fill on a
+    // #1877F2 field is an invisible mark — the exact way a branded button ships
+    // looking like a blank one.
     svg: (
-      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="#1877F2">
+      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
         <path d="M24 12.073c0-6.627-5.373-12-12-12s-12 5.373-12 12c0 5.99 4.388 10.954 10.125 11.854v-8.385H7.078v-3.47h3.047V9.43c0-3.007 1.792-4.669 4.533-4.669 1.312 0 2.686.235 2.686.235v2.953H15.83c-1.491 0-1.956.925-1.956 1.874v2.25h3.328l-.532 3.47h-2.796v8.385C19.612 23.027 24 18.062 24 12.073z"/>
       </svg>
     ),
   },
   github: {
-    label: 'GitHub',
-    color: '#000000',
     svg: (
-      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor">
+      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
         <path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/>
       </svg>
     ),
   },
   apple: {
-    label: 'Apple',
-    color: '#000000',
     svg: (
-      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor">
+      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
         <path d="M17.05 20.28c-.98.95-2.05.8-3.08.35-1.09-.46-2.09-.48-3.24 0-1.44.62-2.2.44-3.06-.35C2.79 15.25 3.51 7.59 9.05 7.31c1.35.07 2.29.74 3.08.8 1.18-.24 2.31-.93 3.57-.84 1.51.12 2.65.72 3.4 1.8-3.12 1.87-2.38 5.98.48 7.13-.57 1.5-1.31 2.99-2.54 4.09l.01-.01zM12.03 7.25c-.15-2.23 1.66-4.07 3.74-4.25.29 2.58-2.34 4.5-3.74 4.25z"/>
       </svg>
     ),
@@ -71,22 +98,29 @@ export function FederatedAuthSection({ providers, onProviderClick, isLoading }:
   return (
     <div className="space-y-3">
       {providers.map((provider) => {
-        const config = providerIcons[provider];
+        const icon = providerIcons[provider];
+        const brand = PROVIDER_BRAND[provider] ?? {
+          label: `Continue with ${provider}`,
+          background: 'var(--bg-default, #ffffff)',
+          color: 'var(--text-primary, #111827)',
+          border: 'var(--border-default, #e5e7eb)',
+        };
         return (
           <button
             key={provider}
             type="button"
             onClick={() => onProviderClick(provider)}
             disabled={isLoading}
+            data-provider={provider}
             className={`w-full px-4 py-3 rounded-lg border-2 font-semibold transition-colors flex items-center justify-center gap-2 disabled:opacity-50 disabled:cursor-not-allowed`}
             style={{
-              border: '1px solid var(--border-default)',
-              color: 'var(--text-primary)',
-              background: 'var(--bg-default)',
+              border: `1px solid ${brand.border}`,
+              color: brand.color,
+              background: brand.background,
             }}
           >
-            {config.svg}
-            Continue with {config.label}
+            {icon.svg}
+            {brand.label}
           </button>
         );
       })}

package/src/hooks/useAvailableProviders.ts

@@ -62,35 +62,58 @@ export function useAvailableProviders(): UseAvailableProvidersResult {
 
         async function fetchProviders() {
             try {
-                // Fetch available providers from Better Auth
-                // Better Auth doesn't have a getProviders equivalent, so we use a static list
-                // based on configured social providers
-                const result: Record<string, { id: string; name: string }> = {
-                    google: { id: 'google', name: 'Google' },
-                };
+                // PAY-2104: THIS USED TO BE A HARDCODED GOOGLE LITERAL.
+                //
+                //   const result = { google: { id: 'google', name: 'Google' } };
+                //
+                // under a comment claiming providers were "loaded dynamically". It
+                // returned Google for EVERY client whatever the tenant had enabled -
+                // a config-shaped constant, so Apple/Facebook (PAY-2104) could never
+                // appear and a client that had DISABLED Google would still see its
+                // button. The real answer is served by /api/auth/settings (the same
+                // route routes/auth/settings.ts builds from the IDP's oauthProviders).
+                const response = await fetch('/api/auth/settings', { cache: 'no-store' });
 
                 if (!mounted) return;
 
-                setRawProviders(result);
-
-                if (result) {
-                    // Filter to OAuth providers only (exclude credentials)
-                    // Map to our FederatedProvider type
-                    const oauthProviders = Object.keys(result)
-                        .filter(id => OAUTH_PROVIDERS.includes(id))
-                        .map(id => PROVIDER_MAP[id])
-                        .filter((p): p is FederatedProvider => p !== undefined);
+                if (!response.ok) {
+                    // FAIL CLOSED. An unreadable policy is not an empty provider list
+                    // that we may then pad with a guess - it is "we do not know". See
+                    // the PAY-1243 rule: never fabricate a provider list.
+                    throw new Error(`Failed to fetch auth settings: ${response.status}`);
+                }
 
-                    setProviders(oauthProviders);
-                } else {
-                    setProviders([]);
+                const body = await response.json().catch(() => null);
+                const settings = body?.data ?? body;
+                if (body?.success === false || !settings) {
+                    throw new Error(body?.error?.code ?? 'POLICY_UNAVAILABLE');
                 }
 
+                // Keep the raw provider rows (id -> the settings row) for callers that
+                // want more than the mapped union type, exactly as before.
+                const enabledIds: string[] = Array.isArray(settings.enabledProviders)
+                    ? settings.enabledProviders.filter((p: unknown): p is string => typeof p === 'string')
+                    : [];
+                const raw: Record<string, { id: string; name: string }> = {};
+                for (const id of enabledIds) raw[id] = { id, name: id };
+
+                if (!mounted) return;
+                setRawProviders(raw);
+
+                // Filter to OAuth providers only (exclude credentials) and map to our
+                // FederatedProvider union, in the IDP's order.
+                const oauthProviders = enabledIds
+                    .filter(id => OAUTH_PROVIDERS.includes(id))
+                    .map(id => PROVIDER_MAP[id])
+                    .filter((p): p is FederatedProvider => p !== undefined);
+
+                setProviders(oauthProviders);
                 setError(null);
             } catch (err) {
                 if (!mounted) return;
                 setError(err instanceof Error ? err : new Error(String(err)));
                 setProviders([]);
+                setRawProviders(null);   // never leave a stale list behind a failure
             } finally {
                 if (mounted) {
                     setIsLoading(false);

package/src/lib/nextauth-secret.ts

@@ -0,0 +1,168 @@
+/**
+ * resolveNextAuthSecret - COMPATIBILITY SHIM (restored 2026-09-30, PAY-2005 / N7).
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS, AND WHY IT IS A SHIM RATHER THAN A FEATURE
+ * ---------------------------------------------------------------------------
+ * The NextAuth-era broker secret resolver was DELETED in
+ *     4d3d29e6  "feat!: Better Auth 4.0.0 — NextAuth fully removed"
+ * and it is intentionally NOT coming back as first-class API: this package is
+ * Better Auth now, and new apps must not resolve a NextAuth secret at all.
+ *
+ * It is restored here ONLY because ONE consumer is still mid-migration and cannot
+ * take the 4.4.x bump without it:
+ *
+ *   CONSUMER THAT NEEDS THIS: the customer portal
+ *   (`payez_idp_admin_web` / VibeID-Customer-Portal). It is pinned at
+ *   @payez/next-mvp 4.0.46 and still runs BOTH next-auth@4.24 and better-auth; its
+ *   `src/lib/server-session.ts` and `src/lib/session-token.ts` (and 5 route files)
+ *   import `resolveNextAuthSecret` from here. Without this export, bumping the
+ *   portal to 4.4.x breaks its build. BAPert ruled (68003) to ship this scoped
+ *   shim rather than force the portal's full NextAuth->BetterAuth migration
+ *   tonight. That migration is tracked as its own card; WHEN IT LANDS, DELETE
+ *   THIS FILE.
+ *
+ * DO NOT add new consumers. If you are starting an app, use Better Auth's own
+ * secret handling; you do not need this.
+ *
+ * ---------------------------------------------------------------------------
+ * BEHAVIOUR (faithful to the 4.0.46 implementation, with one deliberate change)
+ * ---------------------------------------------------------------------------
+ * Priority: (1) process.env.NEXTAUTH_SECRET if set; (2) fetch from the IDP via a
+ * signed client assertion; (3) cache in-memory 5 min and stamp NEXTAUTH_SECRET.
+ *
+ * DELIBERATE CHANGE, 4.0.46 -> here: 4.0.46 validated the fetched secret with
+ * `validateNextAuthSecret`, which this package's 4.4.x no longer exports (it was
+ * renamed to `validateAuthSecret` with an IDENTICAL body). The shim calls
+ * `validateAuthSecret` - same predicate, current name - so there is no second
+ * copy of the rule. The validation semantics are unchanged.
+ *
+ * SERVER-ONLY: the IDP handshake and NEXTAUTH_SECRET are server concerns.
+ */
+import 'server-only';
+import { randomUUID } from 'node:crypto';
+import { validateAuthSecret } from './secret-validation';
+
+let cachedSecret: string | null = null;
+let lastFetchedAt = 0;
+
+const CACHE_TTL_MS = 5 * 60 * 1000;
+
+interface SigningResponse {
+  data?: { client_assertion?: string; clientAssertion?: string; ClientAssertion?: string };
+  client_assertion?: string;
+  clientAssertion?: string;
+  ClientAssertion?: string;
+}
+
+interface SecretResponse {
+  data?: { secret?: string; configuration?: unknown };
+  secret?: string;
+  configuration?: unknown;
+}
+
+/**
+ * Resolve the NextAuth secret (server-only).
+ *
+ * Priority:
+ * 1) Use process.env.NEXTAUTH_SECRET if present (allows overrides/production)
+ * 2) Fetch from the IDP broker endpoint - the IDP handles all Key Vault/signing
+ * 3) Cache result in-memory and set process.env.NEXTAUTH_SECRET for later calls
+ */
+export async function resolveNextAuthSecret(): Promise<string> {
+  // Check if already in environment
+  if (process.env.NEXTAUTH_SECRET && process.env.NEXTAUTH_SECRET.trim() !== '') {
+    return process.env.NEXTAUTH_SECRET;
+  }
+
+  // Check if cached and fresh (within 5 minutes)
+  if (cachedSecret && Date.now() - lastFetchedAt < CACHE_TTL_MS) {
+    return cachedSecret;
+  }
+
+  // Broker mode: fetch from the IDP (the IDP handles all Key Vault/signing)
+  const base = process.env.IDP_URL;
+  if (!base) throw new Error('IDP_URL environment variable is required');
+
+  const clientIdStr = process.env.CLIENT_ID;
+  if (!clientIdStr || clientIdStr.trim() === '') {
+    throw new Error('CLIENT_ID is required (e.g., "ideal_resume_website")');
+  }
+
+  // Step 1: ask the IDP to sign a client assertion (the IDP holds the keys, not us)
+  const signingUrl = `${base.replace(/\/$/, '')}/api/ExternalAuth/sign-client-assertion`;
+  const signingResp = await fetch(signingUrl, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      'X-Client-Id': clientIdStr,
+      'X-Correlation-Id': randomUUID().replace(/-/g, ''),
+    },
+    body: JSON.stringify({
+      issuer: clientIdStr,
+      subject: clientIdStr,
+      audience: 'urn:payez:externalauth:nextauthsecret',
+      expires_in: 60,
+    }),
+    cache: 'no-store',
+  });
+
+  if (!signingResp.ok) {
+    const txt = await signingResp.text().catch(() => 'Unknown error');
+    throw new Error(`Failed to sign client assertion: ${signingResp.status} ${signingResp.statusText} - ${txt}`);
+  }
+
+  const signingBody = (await signingResp.json().catch(() => ({}))) as SigningResponse;
+  const clientAssertion =
+    signingBody?.data?.client_assertion ??
+    signingBody?.data?.clientAssertion ??
+    signingBody?.client_assertion ??
+    signingBody?.clientAssertion ??
+    signingBody?.data?.ClientAssertion ??
+    signingBody?.ClientAssertion;
+
+  if (!clientAssertion || typeof clientAssertion !== 'string') {
+    throw new Error('IDP did not return a valid signed client assertion');
+  }
+
+  // Step 2: use the signed assertion to fetch the NextAuth secret
+  const proxyUrl = `${base.replace(/\/$/, '')}/api/ExternalAuth/next-auth/secret`;
+  const proxyResp = await fetch(proxyUrl, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      'X-Client-Id': clientIdStr,
+      'X-Correlation-Id': randomUUID().replace(/-/g, ''),
+    },
+    body: JSON.stringify({ client_assertion: clientAssertion }),
+    cache: 'no-store',
+  });
+
+  if (!proxyResp.ok) {
+    const txt = await proxyResp.text().catch(() => 'Unknown error');
+    throw new Error(`Proxy error: ${proxyResp.status} ${proxyResp.statusText} - ${txt}`);
+  }
+
+  const proxyBody = (await proxyResp.json().catch(() => ({}))) as SecretResponse;
+  const secret = proxyBody?.data?.secret ?? proxyBody?.secret;
+  // `configuration` is available from the IDP but deliberately not logged.
+
+  if (!secret || typeof secret !== 'string') {
+    throw new Error('Proxy did not return a valid NextAuth secret');
+  }
+
+  // Same predicate as 4.0.46's validateNextAuthSecret, under its current name.
+  const validation = validateAuthSecret(secret);
+  if (!validation.valid) {
+    throw new Error(`Fetched NextAuth secret failed validation: ${validation.reason}`);
+  }
+
+  cachedSecret = secret;
+  lastFetchedAt = Date.now();
+  process.env.NEXTAUTH_SECRET = secret;
+
+  console.log('[NEXTAUTH-SECRET] Resolved from IDP (length:', secret.length + ')');
+  return secret;
+}

package/src/lib/safe-error-response.ts

@@ -124,3 +124,26 @@ export function projectPasswordPolicyRules(json: unknown): string[] | undefined
   if (!details || details.code !== 'password_policy') return undefined;
   return knownPasswordRules(details.rules);
 }
+
+/**
+ * PAY-2103 (AUTH-009 breached-password check): the IdP refuses a password found in a breach corpus with
+ * the typed code `password_breached` in its 400 validation envelope (error.code, or error.details.code,
+ * or a value[] entry while it settles). The reset-password route is ANONYMOUS, so only a BOOLEAN crosses
+ * (`password_breached: true`), never the code text: the page maps the boolean to its own sentence. Reads
+ * only the code, never IdP text.
+ */
+export function projectPasswordBreached(json: unknown): boolean {
+  if (!json || typeof json !== 'object') return false;
+  const top = json as Record<string, unknown>;
+  const err = top.error && typeof top.error === 'object' ? (top.error as Record<string, unknown>) : {};
+  const direct = str(err.code) ?? str(top.code) ?? str(top.error_code);
+  if (direct?.toLowerCase() === 'password_breached') return true;
+  const details = (err.details && typeof err.details === 'object' ? err.details : top.details && typeof top.details === 'object' ? top.details : null) as Record<string, unknown> | null;
+  if (str(details?.code)?.toLowerCase() === 'password_breached') return true;
+  // THE SHAPE THE IdP ACTUALLY SENDS (DotNetPert-Scout, PAY-2103 PR 850caa07a): error.details =
+  // { field:'new_password', code:'password_policy', rules:['password_breached'], requirements:[...] }.
+  // The breach is a member of rules[], not a code - the house envelope carries every password rule
+  // that way. Reading only a code would MISS the real refusal.
+  if (Array.isArray(details?.rules) && (details!.rules as unknown[]).some((r) => typeof r === 'string' && r.toLowerCase() === 'password_breached')) return true;
+  return Array.isArray(details?.value) && (details!.value as unknown[]).some((v) => !!v && typeof v === 'object' && str((v as Record<string, unknown>).code)?.toLowerCase() === 'password_breached');
+}