feat: add attemptWithReason() for login failure reasons (#37)

* feat: add attemptWithReason() for login failure reasons

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 is hard to see: a Google or
passkey signup has a row, so a findFirst by 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.

Two invariants hold the design:

- attempt() keeps returning Promise<boolean>. Widening it would turn
  every `if (!await attempt())` downstream into a permanently false
  branch, since objects are always truthy, and log everyone in without a
  type error at the call site.
- 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.

The reason is a fact, not a message. Deciding what reaches a screen stays
with the application, so the disclosure policy ships as a guide rather
than as configuration.

* docs: correct createAuth signature to include AuthFactoryOptions

The reference declared the factory as `() => AuthInstance<TUser>`, which
has been wrong since per-request autoTouch landed in 36970fe. A bug
report against this package cited the stale signature as evidence that
`auth({ autoTouch: true })` was unsupported, and it is supported.

Author: ramonmalcolm10

__tests__/auth.test.ts

@@ -381,6 +381,109 @@ describe('AuthInstance', () => {
       expect(result).toBe(false);
     });
 
+    describe('attemptWithReason()', () => {
+      it('reports no_user for an address with no account', async () => {
+        const result = await laravelAuth.attemptWithReason({
+          email: 'nobody@b.com',
+          password: 'correct-password',
+        });
+        expect(result).toEqual({ ok: false, reason: 'no_user' });
+      });
+
+      it('reports bad_password for a real account and a wrong password', async () => {
+        const result = await laravelAuth.attemptWithReason({
+          email: 'a@b.com',
+          password: 'wrong',
+        });
+        expect(result).toEqual({ ok: false, reason: 'bad_password' });
+      });
+
+      it('reports no_password for an account that has none (social/passkey signup)', async () => {
+        const social = createAuth<TestUser>({
+          secret: SECRET,
+          cookie: bridge,
+          resolveUser: async () => null,
+          hash,
+          resolveUserByCredentials: async () => ({ id: '2', email: 'g@b.com' }),
+        })();
+
+        const result = await social.attemptWithReason({
+          email: 'g@b.com',
+          password: 'anything',
+        });
+        // The case a second `findFirst` by email cannot see: the row exists,
+        // so "account exists" is true, but no password can ever succeed.
+        expect(result).toEqual({ ok: false, reason: 'no_password' });
+      });
+
+      it('reports rejected when attemptUser declines', async () => {
+        const tokenAuth = createAuth<TestUser>({
+          secret: SECRET,
+          cookie: bridge,
+          resolveUser: async () => null,
+          attemptUser: async (creds) =>
+            creds.token === 'valid' ? { id: '1', email: 'a@b.com' } : null,
+        })();
+
+        expect(await tokenAuth.attemptWithReason({ token: 'bad' })).toEqual({
+          ok: false,
+          reason: 'rejected',
+        });
+        expect(await tokenAuth.attemptWithReason({ token: 'valid' })).toEqual({ ok: true });
+      });
+
+      it('logs in on success and returns no user object', async () => {
+        const result = await laravelAuth.attemptWithReason({
+          email: 'a@b.com',
+          password: 'correct-password',
+        });
+
+        expect(result).toEqual({ ok: true });
+        // The password hash must not ride back out on the result.
+        expect(result).not.toHaveProperty('user');
+        expect(await laravelAuth.check()).toBe(true);
+      });
+
+      it('still verifies against the dummy hash on a user miss', async () => {
+        let verifyCalls = 0;
+        const countingHash = {
+          make: (p: string) => hash.make(p),
+          verify: (p: string, h: string) => {
+            verifyCalls++;
+            return hash.verify(p, h);
+          },
+        };
+
+        const auth = createAuth<TestUser>({
+          secret: SECRET,
+          cookie: bridge,
+          resolveUser: async () => null,
+          hash: countingHash,
+          resolveUserByCredentials: async () => null,
+        })();
+
+        // Returning the reason must not buy back the timing oracle the dummy
+        // hash exists to close: the miss path still pays for a verify.
+        expect(await auth.attemptWithReason({ email: 'x@b.com', password: 'p' }))
+          .toEqual({ ok: false, reason: 'no_user' });
+        expect(verifyCalls).toBe(1);
+      });
+
+      it('agrees with attempt() on every path', async () => {
+        const cases = [
+          { email: 'a@b.com', password: 'correct-password' },
+          { email: 'a@b.com', password: 'wrong' },
+          { email: 'nobody@b.com', password: 'correct-password' },
+        ];
+
+        for (const creds of cases) {
+          const bool = await laravelAuth.attempt(creds);
+          const rich = await laravelAuth.attemptWithReason(creds);
+          expect(rich.ok).toBe(bool);
+        }
+      });
+    });
+
     it('strips password from lookup credentials', async () => {
       let receivedCreds: Record<string, any> = {};
       const authWithSpy = createAuth<TestUser>({

auth-instance.ts

@@ -1,5 +1,6 @@
 import type {
   AnyUser,
+  AttemptResult,
   AuthInstance,
   ConfigurableCookieOptions,
   CookieBridge,
@@ -171,6 +172,57 @@ export function createAuthInstance<TUser extends AnyUser>(
     }
   }
 
+  /**
+   * The one implementation behind both `attempt()` and `attemptWithReason()`.
+   *
+   * Ordering here is load-bearing: hash.verify() runs unconditionally, before
+   * any branch that could return early, so a caller who only logs the reason
+   * still gets the constant-time property it never asked to give up.
+   */
+  async function runAttempt(
+    credentials: Record<string, any>,
+    options?: LoginOptions,
+  ): Promise<AttemptResult> {
+    // Escape hatch: attemptUser handles everything
+    if (deps.attemptUser) {
+      const user = await deps.attemptUser(credentials);
+      if (!user) return { ok: false, reason: 'rejected' };
+      await writeSession(user, options);
+      return { ok: true };
+    }
+
+    // Laravel-style: strip password, resolve user, verify hash
+    if (deps.hash && deps.resolveUserByCredentials) {
+      const { [deps.credentialKey]: password, ...lookup } = credentials;
+      // Coerce non-string passwords (missing, arrays from query strings, etc.)
+      // to '' so the flow returns false instead of throwing — and still runs
+      // the verify below to keep timing uniform.
+      const plaintext = typeof password === 'string' ? password : '';
+      const dbUser = await deps.resolveUserByCredentials(lookup);
+
+      // Run verify even on miss against a dummy hash — prevents user enumeration via timing
+      const rawStoredHash = dbUser
+        ? (dbUser as Record<string, any>)[deps.passwordField]
+        : undefined;
+      const storedHash = typeof rawStoredHash === 'string' && rawStoredHash
+        ? rawStoredHash
+        : undefined;
+      const hashToCheck = storedHash ?? (await getDummyHash(deps.hash));
+      const ok = await deps.hash.verify(plaintext, hashToCheck);
+
+      if (!dbUser) return { ok: false, reason: 'no_user' };
+      if (!storedHash) return { ok: false, reason: 'no_password' };
+      if (!plaintext || !ok) return { ok: false, reason: 'bad_password' };
+
+      await writeSession(dbUser as TUser, options);
+      return { ok: true };
+    }
+
+    throw new Error(
+      'Provide either attemptUser() or both hash + resolveUserByCredentials in config to use attempt()',
+    );
+  }
+
   return {
     async login(user: TUser, options?: LoginOptions): Promise<void> {
       await writeSession(user, options);
@@ -186,42 +238,18 @@ export function createAuthInstance<TUser extends AnyUser>(
     },
 
     async attempt(credentials: Record<string, any>, options?: LoginOptions): Promise<boolean> {
-      // Escape hatch: attemptUser handles everything
-      if (deps.attemptUser) {
-        const user = await deps.attemptUser(credentials);
-        if (!user) return false;
-        await writeSession(user, options);
-        return true;
-      }
-
-      // Laravel-style: strip password, resolve user, verify hash
-      if (deps.hash && deps.resolveUserByCredentials) {
-        const { [deps.credentialKey]: password, ...lookup } = credentials;
-        // Coerce non-string passwords (missing, arrays from query strings, etc.)
-        // to '' so the flow returns false instead of throwing — and still runs
-        // the verify below to keep timing uniform.
-        const plaintext = typeof password === 'string' ? password : '';
-        const dbUser = await deps.resolveUserByCredentials(lookup);
-
-        // Run verify even on miss against a dummy hash — prevents user enumeration via timing
-        const rawStoredHash = dbUser
-          ? (dbUser as Record<string, any>)[deps.passwordField]
-          : undefined;
-        const storedHash = typeof rawStoredHash === 'string' && rawStoredHash
-          ? rawStoredHash
-          : undefined;
-        const hashToCheck = storedHash ?? (await getDummyHash(deps.hash));
-        const ok = await deps.hash.verify(plaintext, hashToCheck);
-
-        if (!dbUser || !storedHash || !plaintext || !ok) return false;
-
-        await writeSession(dbUser as TUser, options);
-        return true;
-      }
+      // Stays a boolean forever. Widening this return type would turn every
+      // `if (!await attempt())` in every downstream app into a permanently
+      // false branch — an object is always truthy — and log everyone in
+      // without a type error at the call site. Use attemptWithReason().
+      return (await runAttempt(credentials, options)).ok;
+    },
 
-      throw new Error(
-        'Provide either attemptUser() or both hash + resolveUserByCredentials in config to use attempt()',
-      );
+    async attemptWithReason(
+      credentials: Record<string, any>,
+      options?: LoginOptions,
+    ): Promise<AttemptResult> {
+      return runAttempt(credentials, options);
     },
 
     async logout(): Promise<void> {

docs/src/content/docs/api/create-auth.mdx

@@ -3,12 +3,14 @@ title: createAuth
 description: API reference for createAuth — the core session auth factory.
 ---
 
-import { Tabs, TabItem } from '@astrojs/starlight/components';
+import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
 
 ## Signature
 
 ```typescript
-function createAuth<TUser>(config: AuthConfig<TUser>): () => AuthInstance<TUser>
+function createAuth<TUser>(
+  config: AuthConfig<TUser>,
+): (options?: AuthFactoryOptions) => AuthInstance<TUser>
 ```
 
 `createAuth` is the main entry point for session-based authentication. It accepts an `AuthConfig` object and returns a **factory function**. Each call to the factory produces an `AuthInstance` scoped to the current request's cookies.
@@ -184,6 +186,47 @@ if (!success) {
 }
 ```
 
+### attemptWithReason
+
+```typescript
+attemptWithReason(
+  credentials: Record<string, unknown>,
+  options?: LoginOptions,
+): Promise<AttemptResult>
+```
+
+Identical work to `attempt()` — same lookup, same verification, same login on success — but returns *why* it failed instead of discarding it. No extra query: `attempt()` already resolved the user and already knew which branch failed.
+
+```typescript
+const result = await auth().attemptWithReason({
+  email: 'user@example.com',
+  password: 'their-password',
+});
+
+if (!result.ok) {
+  return { error: messageFor(result.reason) };
+}
+```
+
+| `reason` | Meaning |
+| --- | --- |
+| `no_user` | Nothing matched the lookup. |
+| `no_password` | The account exists but has no password set — a social or passkey signup. |
+| `bad_password` | The password did not match. |
+| `rejected` | `attemptUser()` declined. Why is that callback's business, not the library's. |
+
+<Aside type="caution" title="A reason is a fact, not a message">
+  Three of the four confirm whether an address is registered. Putting any of them
+  on a screen is a disclosure decision that belongs to your application — see
+  [Login error messages](/ideal-auth/guides/login-error-messages/) for the
+  probe-budget pattern. `bad_password` must never reach a user in any form: that
+  a password was close is the one thing a login must not confirm.
+</Aside>
+
+Success returns `{ ok: true }` and no user object. The resolved row still carries the password hash at that point, and handing it back is how it ends up somewhere it shouldn't — call [`user()`](#user) for the session-safe copy.
+
+Timing is unaffected. Both methods run `hash.verify()` unconditionally before any branch, against a dummy hash when no user was found, so a caller that only logs the reason keeps the constant-time property it never asked to give up.
+
 ### logout
 
 ```typescript
@@ -409,7 +452,10 @@ All types are available as type-only exports:
 
 ```typescript
 import type {
+  AttemptFailure,
+  AttemptResult,
   AuthConfig,
+  AuthFactoryOptions,
   AuthInstance,
   CookieBridge,
   CookieOptions,