feat: add attemptWithReason() for login failure reasons

[ramonmalcolm10]

Why

attempt() resolves the user and verifies the hash, then collapses both into a boolean. Callers who want to tell someone "no account found with that email" were paying a second lookup to recover what the attempt had already established one line earlier.

That workaround is also wrong in a way that's hard to see: a Google or passkey signup has a row, so findFirst({ where: { email } }) reports the account as existing, and the user is told "invalid email or password" for an account where no password can ever succeed. Only the attempt itself can tell the difference — attemptWithReason() reports it as no_password.

API

const result = await auth().attemptWithReason({ email, password });

if (!result.ok) {
  result.reason; // 'no_user' | 'no_password' | 'bad_password' | 'rejected'
}

Two invariants the design rests on

1. attempt() keeps returning Promise<boolean>. Widening it would turn every if (!await attempt()) downstream into a permanently false branch — objects are always truthy — and log everyone in with no type error at the call site.
2. hash.verify() still runs unconditionally before any branch that can return early, against the cached dummy hash on a user miss. Asking for the reason must not buy back the timing oracle that exists to close. There's a test asserting the miss path still pays for a verify.

Disclosure stays with the caller

The reason is a fact, not a message. What reaches a screen is an application decision, so the policy ships as a guide rather than as configuration — including the probe-budget pattern, the "never surface bad_password" rule, and the point that withholding at login buys little if registration already answers the same question.

Contents

• types.ts — AttemptFailure, AttemptResult, AuthInstance.attemptWithReason
• auth-instance.ts — attempt() body hoisted into a shared runAttempt()
• index.ts — exports both types
• __tests__/auth.test.ts — 7 tests: one per reason, success shape, dummy-hash-still-runs, agreement with attempt()
• docs — API reference section + new Login Error Messages guide

Second commit is unrelated housekeeping kept separate: the reference declared the factory as () => AuthInstance<TUser>, stale since per-request autoTouch landed in 36970fe. A bug report cited it as evidence auth({ autoTouch: true }) was unsupported.

Verification

bun test → 233 pass, 0 fail. Docs build clean.