Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ashcroft08/provesa-web/llms.txt

Use this file to discover all available pages before exploring further.

PROVESA Web uses Better Auth for secure authentication and user management. This guide covers user administration and access control.

​
Authentication System

PROVESA Web implements a secure authentication system with:
  • Email/Password Login: Standard credential-based authentication
  • Password Recovery: Email-based password reset flow
  • Session Management: Secure session handling with Better Auth
  • Route Protection: Admin routes protected by authentication middleware

​
User Roles

Currently, PROVESA Web supports a single admin role:
RoleAccess LevelDescription
AdministratorFull AccessComplete control over all admin panel features
Future versions may include additional roles like Editor, Viewer, or Content Manager with granular permissions.

​
Creating Admin Users

New administrators are created through the database seeding process during initial setup.

​
Initial Admin Setup

During installation, a default admin account is created:
1

Run Database Migration

pnpm db:push
This creates the necessary database tables.
2

Run Seed Command

pnpm db:seed
This creates the default admin user and theme settings.
3

Check Seed Output

The seed script will output the default admin credentials:
  • Default email: Check the seed file in src/lib/server/db/seed.js
  • Default password: Set during seeding
Security Best Practice: Change the default admin password immediately after first login.

​
Managing Users

​
Accessing User Management

A dedicated user management interface is under development. Currently at /admin/users, which shows a placeholder page.
For now, users are managed directly through:
  1. Database Tools: Using Drizzle Studio or direct database access
  2. Command Line: Using database seeding scripts

​
Using Drizzle Studio

Drizzle Studio provides a GUI for database management:
1

Open Drizzle Studio

pnpm db:studio
This launches the database GUI in your browser.
2

Navigate to Users Table

Find and click the user table in the left sidebar.
3

View or Edit Users

  • View existing user records
  • Edit user details directly
  • Add new user entries
To add a new administrator:
  1. Open the user table in Drizzle Studio
  2. Click “Add Row” or similar option
  3. Enter user details:
    • name: Administrator’s full name
    • email: Login email (must be unique)
    • emailVerified: Set to current timestamp
  4. Save the record
  5. Set password using Better Auth’s password hashing

​
Password Management

​
Password Requirements

Better Auth enforces secure password standards:
  • Minimum length requirements
  • Secure bcrypt hashing
  • Protection against common passwords

​
Changing Your Password

1

Log In to Admin Panel

Access /admin with your current credentials.
2

Use Password Reset Flow

Currently, password changes require using the password recovery flow:
  1. Log out of the admin panel
  2. Click “¿Olvidaste tu contraseña?” on login page
  3. Enter your admin email
  4. Check email for reset link
  5. Follow link to set new password

​
Password Recovery Process

The password recovery system works as follows:
1

Request Password Reset

Navigate to /recuperar and enter your email address.
2

Receive Email

A password reset email is sent via Gmail (configured in environment variables):
  • Contains secure reset token
  • Link valid for limited time
  • Sent to registered email address
3

Reset Password

Click the link in the email to access /restablecer-password:
  • Enter new password
  • Confirm password
  • Submit to update
4

Login with New Password

Use your new password to access the admin panel.

​
Email Configuration

Password recovery requires Gmail SMTP configuration.

​
Setting Up Gmail for Password Reset

1

Enable 2-Factor Authentication

On your Google account, enable 2FA in security settings.
2

Generate App Password

Create an app-specific password:
  1. Go to Google App Passwords
  2. Select “Mail” and your device
  3. Generate password
  4. Copy the 16-character password
3

Update Environment Variables

Add to your .env file:
GMAIL_USER="your-email@gmail.com"
GMAIL_APP_PASSWORD="your-16-char-app-password"
4

Test Email Sending

Trigger a password reset to verify email delivery.
Never commit the .env file to version control. Keep credentials secure.

​
Session Management

​
How Sessions Work

Better Auth manages user sessions:
  • Sessions stored in database
  • Secure session tokens in cookies
  • Automatic expiration after inactivity
  • Protection against CSRF attacks

​
Session Configuration

Session settings are configured in src/lib/server/auth.js: 
export const auth = betterAuth({
  database: db,
  emailAndPassword: {
    enabled: true,
  },
  // Additional Better Auth configuration
});

​
Logging Out

Users can log out from the admin panel:
  1. Click the logout icon in the sidebar user profile
  2. Session is terminated server-side
  3. Redirected to login page

​
Security Best Practices

  • Use strong, unique passwords for each admin
  • Change default passwords immediately
  • Enable 2FA on Gmail accounts used for recovery
  • Rotate passwords periodically (every 90 days)
  • Never share admin credentials

​
Route Protection

Admin routes are protected by authentication middleware:

​
Protected Routes

All routes under /admin/* require authentication:
  • /admin - Main dashboard
  • /admin/users - User management (under development)
  • All admin panel sections

​
Authentication Flow

​
Layout Server Protection

The file src/routes/admin/+layout.server.js enforces authentication: 
export const load = async (event) => {
  const { user } = event.locals;
  
  if (!user) {
    throw redirect(302, '/login');
  }
  
  return { user };
};

​
Troubleshooting

​
Common Issues

Symptoms: Redirected to login even after entering credentialsSolutions:
  • Clear browser cookies
  • Check if user exists in database
  • Verify password is correct
  • Check Better Auth configuration
  • Review server logs for errors
Symptoms: No email arrives after requesting password resetSolutions:
  • Check spam/junk folder
  • Verify GMAIL_USER and GMAIL_APP_PASSWORD in .env
  • Confirm Gmail app password is correct
  • Check server logs for email sending errors
  • Verify email address is correct in database
Symptoms: Logged out frequently during useSolutions:
  • Check Better Auth session configuration
  • Review session timeout settings
  • Ensure cookies are enabled in browser
  • Check for clock synchronization issues

​
Future User Management Features

Planned enhancements include:
  • User Management UI: Dedicated interface for adding/editing users
  • Role-Based Access Control: Multiple permission levels
  • Activity Logging: Track admin actions and changes
  • Two-Factor Authentication: Additional security layer
  • User Invitations: Email-based invite system

​
Next Steps

Admin Panel Usage

Learn to navigate the admin interface

Deployment

Deploy your site securely to production

Build docs developers (and LLMs) love

Get started for freeTalk to us