fix(auth): keep userGuid on session after better-auth 1.6 upgrade + broken-session recovery

[chriskehayias]

Problem

better-auth 1.6 changed how additional user fields are parsed from the OAuth
provider profile. A user additionalField declared with input: false no
longer flows through when a value is supplied — in 1.6.11 the parser
(parseAdditionalUserInput, formerly parseAdditionalUserInputFromProviderProfile)
throws "userGuid is not allowed to be set".

Our userGuid field (MP User_GUID / OAuth sub) is populated server-side
via mapProfileToUser, so input: false broke it: session.user.userGuid
became undefined, which breaks every MP profile lookup — blank header avatar,
dead (non-interactive) user menu, and no way to sign out.

This shipped via the routine bump of better-auth from 1.4.x → 1.6.x. CI (build +
lint + unit tests) does not exercise a real OAuth login, so it passed silently.

Changes

Fix (fix(auth) commit)

• Flip userGuid to input: true; extract to an exported userAdditionalFields
  const so a test can assert against the real config. Safe here: the app uses
  genericOAuth only — no email/password signup or update-user endpoint, so the
  field is only ever set server-side from the verified OAuth profile.
• Add a regression guard in src/auth.test.ts that runs the real better-auth
  parser (parseAdditionalUserInput from better-auth/db) against the real
  field config — fails if someone flips it back OR a future better-auth version
  changes provider-profile parsing again.
• Correct auth reference docs (user-identity.md, sessions.md), add a Better
  Auth upgrade checklist, and elevate the in-memory DB-adapter warning.

Recovery (feat(auth) commit)

• AuthWrapper: a session with no userGuid now redirects to /session-error
  instead of rendering a dead app with no sign-out.
• New /session-error page: recovery screen with a handleSignOut form button,
  placed outside the (web) route group so it can't redirect-loop.
• auth-wrapper.test.tsx covers all branches (no session → /signin,
  no/null userGuid → /session-error, healthy → children).

Verification

• npm run lint — clean
• npm run test:run — 670/670 pass, incl. the new real-library guard
• npm run build — succeeds; emits the /session-error route

⚠️ Manual OAuth smoke test still required — automated checks pass whether or
not userGuid actually reaches the session. After merge: sign out, log in
fresh, open /api/auth/get-session, confirm user.userGuid is present and the
avatar/menu render with a working sign-out.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!