feat(auth): error-classification layer + passkey end-to-end

Two interlocking fixes driven by a production lockout incident.

## Bug that motivated this

A fresh schema-drift column (auth.users.onboarding_completed_at) made
every Better Auth query crash with Postgres 42703. The /login wrapper
swallowed the non-2xx and mapped it onto a generic "401 Invalid
credentials" AND bumped the password lockout counter — so 5 legit
login attempts against a broken DB would have locked every real user
out of their own account. Same wrapper pattern on /register, /refresh,
/reset-password etc. The 30-minute hunt ended in a one-off repro
script that finally surfaced the real Postgres error.

The user-facing passkey button additionally returned generic 404s on
every login-page mount because the route wasn't registered (the DB
schema existed, the Better Auth plugin wasn't wired).

## Phase 1 — Error classification (services/mana-auth/src/lib/auth-errors)

- 19-code AuthErrorCode taxonomy (INVALID_CREDENTIALS, EMAIL_NOT_VERIFIED,
  ACCOUNT_LOCKED, SERVICE_UNAVAILABLE, PASSKEY_VERIFICATION_FAILED, …)
- classifyFromResponse/classifyFromError handle: Better Auth APIError
  (duck-typed on `name === 'APIError'`), Postgres errors (23505 unique,
  42703/08xxx → infra), ZodError, fetch/ECONNREFUSED network errors,
  bare Error, unknown.
- respondWithError routes the structured response, logs at the right
  level, fires the correct security event, and CRITICALLY only bumps
  the lockout counter for actual credential failures — SERVICE_UNAVAILABLE
  and INTERNAL never touch lockout.
- All 12 endpoints in routes/auth.ts refactored (/login, /register,
  /logout, /session-to-token, /refresh, /validate, /forgot-password,
  /reset-password, /resend-verification, /profile GET+POST,
  /change-email, /change-password, /account DELETE).
- Fixed pre-existing auth.api.forgetPassword typo (→ requestPasswordReset).
- shared-logger + requestLogger middleware wired in index.ts; all
  console.* calls in the service removed.

## Phase 2 — Passkey end-to-end (@better-auth/passkey 1.6+)

- sql/007_passkey_bootstrap.sql: idempotent schema alignment —
  friendly_name→name, +aaguid, transports jsonb→text, +method column
  on login_attempts.
- better-auth.config.ts: passkey plugin wired with rpID/rpName/origin
  from new webauthn config section. rpID defaults to mana.how in prod
  (from COOKIE_DOMAIN), localhost in dev.
- routes/passkeys.ts: 7 wrapper endpoints (capability probe,
  register/options+verify, authenticate/options+verify with JWT mint,
  list, delete, rename). Each routes errors through the classifier;
  authenticate/verify promotes generic INVALID_CREDENTIALS to
  PASSKEY_VERIFICATION_FAILED.
- PasskeyRateLimitService: in-memory per-IP (options: 20/min) and
  per-credential (verify: 10 failures/min → 5 min cooldown) buckets.
  Deliberately separate from the password lockout — different factor,
  different blast radius.
- Client: authService.getPasskeyCapability() async probe, memoised per
  session. authStore.passkeyAvailable reactive state. LoginPage gates
  on === true so a slow probe doesn't flash the button in.
- AuthResult grew a code: AuthErrorCode field; handleAuthError in
  shared-auth prefers the server envelope over the legacy message
  heuristics.

## Tests

- 30 unit tests for the classifier covering every branch (including
  the exact Postgres 42703 shape that started this).
- 9 unit tests for the rate limiter.
- 14 integration tests for the auth routes — the regression test
  explicitly asserts "upstream 500 → 503 + zero lockout bumps".
- 101 tests pass, 0 fail, 30 pre-existing skips unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

packages/shared-auth-ui/src/pages/LoginPage.svelte

@@ -441,6 +441,11 @@
 			scheduleTimeout(() => goto(successRedirect), 600);
 		} else if (result.error === 'Passkey authentication was cancelled') {
 			// User cancelled - don't show error
+		} else if (result.errorCode === 'PASSKEY_NOT_ENABLED') {
+			// Server hasn't provisioned passkey auth yet. Quietly skip —
+			// the passkey button shouldn't have been shown in the first
+			// place (capability gating does that), but conditional UI
+			// triggered on mount can still land here.
 		} else {
 			setError(result.error || t.signInFailed, 'general');
 		}

packages/shared-auth-ui/src/stores/createManaAuthStore.svelte.ts

@@ -105,6 +105,30 @@ export function createManaAuthStore(config: ManaAuthStoreConfig = {}) {
 	let loading = $state(true);
 	let initialized = $state(false);
 
+	// Passkey capability — one-time probe on first access, cached on
+	// the authService itself. The boolean `passkeyAvailable` derived
+	// here is what the LoginPage + SecuritySection gate their UI on.
+	// Seeded to `null` so the UI can distinguish "not yet probed"
+	// from "probed and disabled".
+	let passkeyAvailable = $state<boolean | null>(null);
+	let passkeyProbePromise: Promise<void> | null = null;
+
+	function ensurePasskeyProbe() {
+		if (passkeyAvailable !== null || passkeyProbePromise) return;
+		const authService = getAuthService();
+		if (!authService) return;
+		passkeyProbePromise = (async () => {
+			try {
+				const cap = await authService.getPasskeyCapability();
+				passkeyAvailable = cap.available;
+			} catch {
+				passkeyAvailable = false;
+			} finally {
+				passkeyProbePromise = null;
+			}
+		})();
+	}
+
 	return {
 		// Getters
 		get user() {
@@ -186,6 +210,21 @@ export function createManaAuthStore(config: ManaAuthStoreConfig = {}) {
 			return authService.isPasskeyAvailable();
 		},
 
+		/**
+		 * Reactive flag: `true` once we've probed the server and both
+		 * browser + server support passkeys, `false` when either side
+		 * has said no, `null` while the probe hasn't resolved yet
+		 * (initial mount). The LoginPage gates its passkey button on
+		 * `=== true` so a slow probe doesn't flash the button in.
+		 *
+		 * Triggers the probe lazily on first read so apps that never
+		 * show passkey UI never pay the network round-trip.
+		 */
+		get passkeyAvailable(): boolean | null {
+			ensurePasskeyProbe();
+			return passkeyAvailable;
+		},
+
 		async signInWithPasskey(options?: { conditional?: boolean }) {
 			const authService = getAuthService();
 			if (!authService) return { success: false, error: 'Auth not available on server' };
@@ -207,12 +246,23 @@ export function createManaAuthStore(config: ManaAuthStoreConfig = {}) {
 			if (!authService) return { success: false, error: 'Auth not available on server' };
 			try {
 				const result = await authService.signIn(email, password);
-				if (!result.success) return { success: false, error: result.error || 'Login failed' };
+				if (!result.success) {
+					return {
+						success: false,
+						error: result.error || 'Login failed',
+						errorCode: result.code,
+						retryAfter: result.retryAfter,
+					};
+				}
 				user = await authService.getUserFromToken();
 				await handleAuthenticated();
 				return { success: true };
 			} catch (error) {
-				return { success: false, error: error instanceof Error ? error.message : 'Unknown error' };
+				return {
+					success: false,
+					error: error instanceof Error ? error.message : 'Unknown error',
+					errorCode: 'UNKNOWN' as const,
+				};
 			}
 		},
 
@@ -228,6 +278,8 @@ export function createManaAuthStore(config: ManaAuthStoreConfig = {}) {
 					return {
 						success: false,
 						error: result.error || 'Signup failed',
+						errorCode: result.code,
+						retryAfter: result.retryAfter,
 						needsVerification: false,
 					};
 				if (result.needsVerification) return { success: true, needsVerification: true };

packages/shared-auth-ui/src/types.ts

@@ -41,10 +41,33 @@ export interface AuthServiceInterface {
  * locale-dependent.
  */
 export type AuthErrorCode =
+	// Credential flows
 	| 'INVALID_CREDENTIALS'
 	| 'EMAIL_NOT_VERIFIED'
-	| 'RATE_LIMITED'
+	| 'EMAIL_ALREADY_REGISTERED'
+	| 'WEAK_PASSWORD'
+	// Throttling
 	| 'ACCOUNT_LOCKED'
+	| 'SIGNUP_LIMIT_REACHED'
+	| 'RATE_LIMITED'
+	// Tokens
+	| 'TOKEN_EXPIRED'
+	| 'TOKEN_INVALID'
+	// Two-factor
+	| 'TWO_FACTOR_REQUIRED'
+	| 'TWO_FACTOR_FAILED'
+	// Passkeys
+	| 'PASSKEY_NOT_ENABLED'
+	| 'PASSKEY_CANCELLED'
+	| 'PASSKEY_VERIFICATION_FAILED'
+	// Input / generic
+	| 'VALIDATION'
+	| 'UNAUTHORIZED'
+	| 'NOT_FOUND'
+	// Infra
+	| 'SERVICE_UNAVAILABLE'
+	| 'INTERNAL'
+	// Client-side only (no server match)
 	| 'NETWORK_ERROR'
 	| 'UNKNOWN';