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>

services/mana-auth/src/auth/better-auth.config.ts

@@ -20,6 +20,7 @@ import { jwt } from 'better-auth/plugins/jwt';
 import { organization } from 'better-auth/plugins/organization';
 import { twoFactor } from 'better-auth/plugins/two-factor';
 import { magicLink } from 'better-auth/plugins/magic-link';
+import { passkey } from '@better-auth/passkey';
 import { getDb } from '../db/connection';
 import { organizations, members, invitations } from '../db/schema/organizations';
 import {
@@ -29,6 +30,7 @@ import {
 	verificationTokens,
 	jwks,
 	twoFactorAuth,
+	passkeys,
 } from '../db/schema/auth';
 import {
 	sendPasswordResetEmail,
@@ -78,13 +80,25 @@ export interface JWTCustomPayload {
 	tier: string;
 }
 
+/**
+ * WebAuthn configuration for the passkey plugin. Kept as a separate
+ * argument so the call site (src/index.ts) can wire it in from the
+ * loaded config without coupling better-auth.config.ts to config.ts.
+ */
+export interface BetterAuthWebAuthnOptions {
+	rpId: string;
+	rpName: string;
+	origin: string | string[];
+}
+
 /**
  * Create Better Auth instance
  *
  * @param databaseUrl - PostgreSQL connection URL
+ * @param webauthn - WebAuthn settings for the passkey plugin
  * @returns Better Auth instance
  */
-export function createBetterAuth(databaseUrl: string) {
+export function createBetterAuth(databaseUrl: string, webauthn: BetterAuthWebAuthnOptions) {
 	const db = getDb(databaseUrl);
 
 	return betterAuth({
@@ -108,6 +122,11 @@ export function createBetterAuth(databaseUrl: string) {
 
 				// Two-Factor Authentication table
 				twoFactor: twoFactorAuth,
+
+				// Passkey plugin table — Drizzle field names match
+				// @better-auth/passkey's plugin schema (see src/db/schema/
+				// auth.ts comment for the alignment rationale).
+				passkey: passkeys,
 			},
 		}),
 
@@ -428,6 +447,30 @@ export function createBetterAuth(databaseUrl: string) {
 				},
 				expiresIn: 600, // 10 minutes
 			}),
+
+			/**
+			 * Passkey plugin — WebAuthn registration + authentication.
+			 *
+			 * rpID is the effective domain the credential binds to. For
+			 * cross-subdomain SSO on `*.mana.how`, this MUST be `mana.how`
+			 * (the bare apex), not any subdomain — otherwise a passkey
+			 * registered on app.mana.how won't work on calendar.mana.how.
+			 * In dev this resolves to `localhost`.
+			 *
+			 * `origin` is the full URL(s) where WebAuthn calls are made
+			 * from; a mismatch causes a SecurityError on verify. We pass
+			 * every CORS origin by default.
+			 *
+			 * Note: passkeys don't replace passwords in this build — every
+			 * account keeps its password, and passkey is additive. This
+			 * sidesteps the "user lost all passkeys" recovery-flow that
+			 * passwordless-only accounts would require.
+			 */
+			passkey({
+				rpID: webauthn.rpId,
+				rpName: webauthn.rpName,
+				origin: webauthn.origin,
+			}),
 		],
 	});
 }