fix: distinguish identity session failures

Principal resolution could not tell a broken session store from a genuinely
anonymous request, and did unnecessary database work for callers that never
presented a session at all. Both are corrected here.

Any cookie previously triggered the ambiguity check, so `Cookie: x=y` on an
otherwise anonymous request caused an identity database round trip an
unauthenticated caller could drive with a header they chose themselves.
`hasConfiguredSessionCookie` now parses the Cookie header per RFC 6265 (split
on `;`, name is the text before the first `=`, trimmed) and compares the whole
name exactly — never `includes`, a substring test, or an unanchored regular
expression — so `better-auth.session_token_x`, `x_better-auth.session_token`, a
differently-cased spelling, and a percent-encoded lookalike are all correctly
not the session cookie. A duplicated name still reports true: ambiguity fails
safe towards checking, and reporting true never grants access on its own.

The cookie name is not a second hard-coded copy. One `betterAuthOptions` object
now feeds both `betterAuth()` and Better Auth's own supported `getCookies`
helper, so the detected name — including the `__Secure-` prefix an https baseURL
implies — is derived from the exact configuration Better Auth itself uses, and
drift is structurally impossible rather than merely tested.

The readiness check itself proved almost nothing: `select 1` still succeeded
against a dropped session table, a drifted or removed column, or a revoked
SELECT privilege, so Better Auth's ambiguous null was reported as a genuinely
anonymous request. `probeSessionStore` now plans a real read of the session
relation and the exact columns the adapter depends on, under `where false`:
PostgreSQL resolves the relation, every column, and the caller's privilege at
plan time while matching zero rows, so no session row, token, or user id can be
read, logged, or enumerated by the check. It uses the injected pool, never a
second connection, and stays bounded by the existing timeout.

A missing relation, dropped column, revoked privilege, unreachable connection,
and query timeout now all produce the same sanitized 503 with no relation name,
column name, SQL, driver text, host, or stack — proven against real PostgreSQL,
since that is the only place a broken store looks exactly like an anonymous
request.

Co-Authored-By: Claude Opus 5 <[email protected]>

docs/development/testing.md

@@ -19,8 +19,10 @@ connection and operation (`query_timeout`/`statement_timeout`) database timeouts
 runtime (explicit construction, exact schema mapping, only email/password and rate limiting
 enabled, an explicit `advanced.disableCSRFCheck`/`disableOriginCheck: false` pair, an explicit
 error-only sanitized logger that strips Better Auth's own message and arguments regardless of what
-they contain, pinned 8–128 password-length bounds, sanitized failures, and that a database outage
-during principal resolution is never silently reported as anonymous), and Core migration discovery
+they contain, pinned 8–128 password-length bounds, sanitized failures, exact whole-name
+session-cookie detection that never fires on a prefixed, suffixed, or differently-cased lookalike,
+and that a broken session store during principal resolution is never silently reported as anonymous
+while an unrelated cookie performs no identity database work at all), and Core migration discovery
 (deterministic ordering, the reserved `core` identity, and collision rejection) — all without a
 live database. `apps/api`'s own unit tests cover its pure Hono app factory (route shapes, module
 route mounting/enforcement/CORS/response sanitization, CORS allow/deny/preflight, deterministic 404
@@ -83,6 +85,15 @@ outage during principal resolution producing a sanitized `503` rather than a fal
 starting the API against an unmigrated database creating no tables at all, and a clean listener/pool
 shutdown.
 
+A dedicated group within that suite proves session-store readiness against the real database rather
+than a mock, since that is the only place a broken store looks exactly like an anonymous request: a
+request carrying no cookies and one carrying only an unrelated cookie both resolve as anonymous
+while issuing **no** identity database work at all; a request presenting the configured session
+cookie against a dropped session table, a dropped column, and a revoked `SELECT` privilege each
+produce a sanitized `503 PRINCIPAL_RESOLUTION_FAILED` with no relation name, column name, SQL, or
+driver text in the body or the logs; and a genuinely expired or unknown session against a healthy
+store still resolves as anonymous.
+
 The same suite also proves Better Auth's own origin/CSRF protection is production-equivalent under
 the test runner, not just in a plain Node script: a no-cookie first authentication attempt succeeds
 from a trusted browser origin and is rejected (`403`, no permissive CORS header, no leaked detail)