@payez/next-mvp 4.5.6 → 4.7.9

package/src/auth/session-cookie-clear.ts

@@ -0,0 +1,30 @@
+/**
+ * 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';
+import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
+
+export function expireSessionCookies(response: NextResponse, requestCookieNames: Iterable<string>): void {
+  const sessionCookie = getSessionCookieName();
+  const secureCookie = 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/src/auth/session-reset-link.ts

@@ -0,0 +1,159 @@
+/**
+ * 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).
+ */
+import { safeCallbackPath } from './safe-callback';
+
+export 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 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 const RESET_LINK_TTL_SECONDS = 300;
+
+/** The purpose label for the derived signing key. Changing it invalidates every outstanding reset link. */
+export 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 const RESET_REASONS: readonly string[] = ['stale', 'invalidated'];
+export const RESET_ERRORS: readonly string[] = ['SessionExpired', 'TwoFactorTimeout'];
+
+export interface ResetParams {
+  callbackUrl: string;
+  reason?: string;
+  error?: string;
+}
+
+const encoder = new TextEncoder();
+const FIELD_SEPARATOR = String.fromCharCode(10);
+
+function b64url(bytes: Uint8Array): string {
+  return btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+async function hmacBytes(key: Uint8Array, message: string): Promise<Uint8Array> {
+  const k = await crypto.subtle.importKey('raw', key as BufferSource, { 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: string, message: string): Promise<string> {
+  const derived = await hmacBytes(encoder.encode(secret), 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: string | undefined): Promise<string> {
+  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: string, b: string): boolean {
+  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. */
+export function resetSecret(): string | undefined {
+  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. */
+export function boundSessionCookie(get: (name: string) => string | undefined, plainName: string, secureName: string): string | undefined {
+  return get(secureName) || get(plainName) || undefined;
+}
+
+/** Normalise to exactly what the route will honour, so what is signed is what is verified. */
+export function normaliseResetParams(raw: { callbackUrl?: string | null; reason?: string | null; error?: string | null }): ResetParams {
+  const out: ResetParams = { callbackUrl: safeCallbackPath(raw.callbackUrl ?? '') };
+  if (raw.reason && RESET_REASONS.includes(raw.reason)) out.reason = raw.reason;
+  if (raw.error && 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. */
+export function resetPayload(p: ResetParams, exp: number, binding: string): string {
+  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. */
+export function loginLocation(p: ResetParams): string {
+  let loc = `${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.
+ */
+export async function signedResetHref(
+  route: string,
+  p: ResetParams,
+  secret: string,
+  sessionCookieValue: string | undefined,
+  nowMs: number = Date.now()
+): Promise<string> {
+  const exp = Math.floor(nowMs / 1000) + 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.
+ */
+export async function readResetRequest(
+  search: URLSearchParams,
+  secret: string | undefined,
+  sessionCookieValue: string | undefined,
+  nowMs: number = Date.now()
+): Promise<{ params: ResetParams; signed: boolean }> {
+  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/src/components/auth/CredentialSignInForm.tsx

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

package/src/lib/authorize-resume.ts

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

package/src/lib/bearer-fetch.ts

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