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
 

docs/user/guide-admin.md

@@ -4,18 +4,7 @@ This guide covers the administrative tasks that support a Pulse Signage deployme
 
 ## Accounts and Access
 
-Your account determines which parts of the web application are available to you. Administrators can invite users, create or edit accounts, assign roles, reset passwords, and remove accounts that are no longer needed.
-
-### Inviting a User
-
-Use the invitation workflow when the person should create their own account:
-
-1. Enter the recipient's email address and display name.
-2. Select the roles the person should receive after accepting the invitation.
-3. Send the invitation.
-4. Ask the recipient to follow the invitation message and complete account setup.
-
-Assign the smallest role set that allows the person to do their work. Review the selected roles before sending because the invitation applies them when the account is accepted. If there are no roles available, create a suitable role before sending the invitation.
+Your account determines which parts of the web application are available to you. Administrators can create or edit accounts, assign roles, reset passwords, and remove accounts that are no longer needed.
 
 ### Managing Existing Users
 
@@ -30,6 +19,14 @@ The current administrator account is protected from actions that would remove or
 
 If you cannot see a feature or action described in the user guides, ask an administrator to check your account rather than assuming the feature is unavailable.
 
+### Requiring Two-Factor Authentication
+
+Enable **Require two-factor authentication** when creating or editing a role. The requirement applies when any of a user's assigned roles has the toggle enabled. Existing roles default to off.
+
+Users without an enrolled authenticator are restricted to My account until they complete setup. Users cannot unlink their authenticator while a role requires it. Administrator authenticator recovery remains available, but the user must enroll again before accessing the rest of the application.
+
+Turning the role toggle off does not disable an authenticator that a user has already enrolled.
+
 ## Fonts
 
 Managed fonts are uploaded once to the deployment and can then be enabled for the editor and players. They are separate from slide media and are intended for font-family choices in text and data regions.
@@ -80,13 +77,13 @@ Weather Providers stores shared credentials for the configured weather services.
 
 ### Security and Sessions
 
-Security and Sessions contains deployment-wide controls for authentication and session behavior. Review these settings when changing login policy, session lifetime, or security controls. Test the change with a non-administrator account where possible so an overly restrictive setting does not prevent normal users from working.
+Security and Sessions contains password and account policies, the option for users to revoke other sessions, and whether administrators may mark user email addresses verified. Sessions expire after 14 days with no active-session cap. Sign-in throttling uses fixed built-in limits: up to 30 requests per 15 minutes generally, with username sign-in limited to 5. Resetting these request limits does not clear per-account authenticator lockouts.
 
 ### Email Delivery and Templates
 
-Email Delivery configures SMTP for messages such as password recovery and account verification. Check the SMTP host, port, security mode, and enabled state before relying on invitations or recovery emails.
+Email Delivery configures SMTP for password recovery and account verification. Check the SMTP host, port, security mode, and enabled state before relying on recovery emails.
 
-Email Templates controls the messages sent by the application. Keep the wording clear and verify links and sender details after changing a template. Send a test invitation or recovery message when the deployment's email settings change.
+Email Templates controls the messages sent by the application. Keep the wording clear and verify codes and sender details after changing a template. Send a test email when the deployment's email settings change.
 
 ### Audit Logging and Diagnostics
 
@@ -112,6 +109,8 @@ Scheduled tasks are service operations, not content settings. Change a source's
 
 The Audit Log records authentication, security, session, and other important administrative events. Filter by category or event type, search by event, actor, or target, and review the time, source address, user agent, and recorded changes.
 
+Audited content updates record only changed fields and their old and new values; empty update records are skipped. Template regions are compared by their stable region keys. Playlist changes include slide order, durations, groups, and schedules. Generated QR SVGs and preview images, including template defaults, are represented by byte counts and SHA-256 fingerprints rather than full payloads, so those assets cannot be reconstructed from the audit log. Existing audit entries and category settings are unchanged.
+
 Use the audit log to answer questions such as:
 
 - Who changed a user, setting, source, or player-related value?