Release v2.20.1: migrate authentication to Better Auth

docs/technical/schema.md

@@ -7,45 +7,60 @@ Tables generally use a numeric auto-increment `id` primary key. The relationship
 
 ## Admin
 
-- `a_users` - admin user accounts and password hashes.
+- `a_users` - admin user profiles and app-specific account controls.
 - `a_roles` - named role definitions.
 - `a_permissions` - permission catalog seeded from the application constants.
 - `a_role_permissions` - many-to-many mapping between roles and permissions.
 - `a_user_roles` - many-to-many mapping between users and roles.
-- `a_sessions` - persisted admin session tokens.
-- `a_account_tokens` - short-lived account verification and password-reset tokens.
-- `a_user_invitations` - pending user invitations and assigned role ids.
-- `a_login_attempts` - login rate-limit and lockout state.
+- `a_sessions` - Better Auth session tokens with application View-as metadata.
+- `a_accounts` - Better Auth credentials and linked identity-provider accounts.
+- `a_verifications` - Better Auth email OTP verification and reset challenges.
+- `a_user_two_factors` - Better Auth authenticator secrets, backup codes, and per-user verification lock state.
+- `a_user_passkeys` - Better Auth passkey credentials and authenticator metadata.
+- `a_login_attempts` - Better Auth database-backed rate-limit counters.
 
 ### `a_users`
 
-- `id`, `name`, `username`, `email`, `email_verified_at`, `pending_email`, `pending_email_token_hash`, `pending_email_expires_at`, `password_hash`, `password_salt`, `password_iterations`, `must_change_password`, `account_locked`, `last_login_at`, `last_login_ip`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- `id`, `name`, `username`, `email`, `email_verified`, `image`, `pending_email`, `must_change_password`, `account_locked`, `created_at`, `created_by`, `modified_at`, `modified_by`
 - `username` is unique.
+- `email` is Better Auth's unique, non-null email identity; synthetic addresses are used when the app email is absent.
 
-### `a_account_tokens`
+### `a_accounts`
 
-- `id`, `user_id`, `token_type`, `token_hash`, `expires_at`, `used_at`, `created_at`
-- `token_hash` is unique.
+- `id`, `account_id`, `provider_id`, `user_id`, `access_token`, `refresh_token`, `id_token`, `access_token_expires_at`, `refresh_token_expires_at`, `scope`, `password`, `created_at`, `updated_at`
+- `(provider_id, account_id)` is unique.
+- Credential passwords are stored in `password` on the `credential` provider account using Better Auth's native scrypt format; legacy PBKDF2 hashes upgrade after successful sign-in. Password hashes are not stored on `a_users`.
 - Foreign key:
         - `user_id` -> `a_users.id` with `ON DELETE CASCADE`
-- Indexed by `(token_type, token_hash, expires_at)` and `(user_id, token_type)`.
 
-### `a_user_invitations`
+### `a_verifications`
 
-- `id`, `email`, `name`, `role_ids_json`, `token_hash`, `expires_at`, `used_at`, `created_at`, `created_by`
-- `token_hash` is unique.
-- Indexed by `(email, used_at, expires_at)` and `(created_by, created_at)`.
+- `id`, `identifier`, `value`, `expires_at`, `created_at`, `updated_at`
+- Indexed by `identifier`; Better Auth stores one-time email codes and their expiry here.
+
+### `a_user_two_factors`
+
+- `id`, `user_id`, `secret`, `backup_codes`, `verified`, `failed_verification_count`, `locked_until`
+- `user_id` is unique; each user has at most one authenticator record.
+- Foreign key: `user_id` -> `a_users.id` with `ON DELETE CASCADE`.
+
+### `a_user_passkeys`
+
+- `id`, `name`, `public_key`, `user_id`, `credential_id`, `counter`, `device_type`, `backed_up`, `transports`, `created_at`, `aaguid`
+- `credential_id` is unique; `user_id` is indexed.
+- Foreign key: `user_id` -> `a_users.id` with `ON DELETE CASCADE`.
 
 ### `a_login_attempts`
 
-- `id`, `rate_key`, `failed_count`, `last_failed_at`, `locked_until`, `created_at`, `modified_at`
+- `id`, `rate_key`, `failed_count`, `last_request`
 - `rate_key` is unique.
 
 ### `a_roles`
 
-- `id`, `role_key`, `name`, `description`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- `id`, `role_key`, `name`, `description`, `require_two_factor`, `created_at`, `created_by`, `modified_at`, `modified_by`
 - `role_key` is unique.
 - `name` is unique.
+- `require_two_factor` defaults to false; users must enroll when any assigned role requires two-factor authentication.
 
 ### `a_permissions`
 
@@ -294,9 +309,13 @@ erDiagram
         }
         A_SESSIONS {
         }
-        A_ACCOUNT_TOKENS {
+        A_ACCOUNTS {
         }
-        A_USER_INVITATIONS {
+        A_VERIFICATIONS {
+        }
+        A_USER_TWO_FACTORS {
+        }
+        A_USER_PASSKEYS {
         }
         A_LOGIN_ATTEMPTS {
         }
@@ -354,7 +373,9 @@ erDiagram
         A_ROLES ||--o{ A_ROLE_PERMISSIONS : has
         A_PERMISSIONS ||--o{ A_ROLE_PERMISSIONS : granted_to
         A_USERS ||--o{ A_SESSIONS : owns
-        A_USERS ||--o{ A_ACCOUNT_TOKENS : has
+        A_USERS ||--o{ A_ACCOUNTS : has
+        A_USERS ||--o| A_USER_TWO_FACTORS : secures_with
+        A_USERS ||--o{ A_USER_PASSKEYS : registers
         A_USERS o|--o{ O_AUDIT_EVENTS : acts
         I_API_SOURCE_GROUPS ||--o{ I_API_SOURCES : contains