================================================================================
VERSION 2.2 - SECURITY & AUTHENTICATION SYSTEM
================================================================================

CRITICAL SECURITY UPDATE
This update adds login authentication, user management, and data protection.

================================================================================
WHAT'S NEW IN v2.2
================================================================================

AUTHENTICATION SYSTEM:
✓ Secure login/logout functionality
✓ Password hashing (bcrypt)
✓ Session management
✓ Remember me functionality
✓ Account lockout after failed attempts
✓ Activity logging

USER MANAGEMENT:
✓ Multi-user support
✓ Role-based access control (Admin, Manager, User, Viewer)
✓ User creation/management (Admin only)
✓ Password change functionality
✓ User status management

SECURITY FEATURES:
✓ All pages protected (require login)
✓ CSRF protection
✓ SQL injection prevention
✓ XSS protection
✓ Failed login attempt tracking
✓ Session token validation
✓ IP address logging

DATA PROTECTION:
✓ User activity tracking
✓ Created_by/Updated_by fields on all tables
✓ Audit trail
✓ Secure password storage

================================================================================
STEP 1: BACKUP YOUR DATABASE
================================================================================

CRITICAL: Always backup before updating!

mysqldump -u username -p investor_db > backup_v2.1_before_security.sql

================================================================================
STEP 2: RUN DATABASE UPDATE
================================================================================

Import the authentication SQL file:

mysql -u username -p investor_db < database/add_authentication.sql

This will create:
✓ users table
✓ user_sessions table
✓ activity_log table
✓ login_attempts table
✓ Add created_by/updated_by to existing tables
✓ Create 2 default users (admin & manager)

================================================================================
STEP 3: DEFAULT LOGIN CREDENTIALS
================================================================================

⚠️ IMPORTANT: Change these passwords IMMEDIATELY after first login!

ADMIN ACCOUNT:
Username: admin
Password: Admin@123
Role: Admin (full access)

MANAGER ACCOUNT:
Username: manager
Password: Manager@123
Role: Manager (limited access)

================================================================================
STEP 4: UPLOAD NEW FILES
================================================================================

Upload these NEW files:

Core Authentication:
  includes/auth.php                 - Authentication handler
  login.php                         - Login page
  logout.php                        - Logout script
  access_denied.php                 - Access denied page

User Management:
  forms/user_management.php         - User management (Admin only)
  forms/change_password.php         - Change password
  forms/profile.php                 - User profile (optional)
  forms/activity_log.php            - Activity log (Admin only)

Database:
  database/add_authentication.sql   - Database update

================================================================================
STEP 5: REPLACE MODIFIED FILES
================================================================================

Replace this MODIFIED file:
  includes/header.php               - Now includes authentication

================================================================================
STEP 6: TEST THE SYSTEM
================================================================================

1. Visit your site URL
2. You should be redirected to login.php
3. Login with admin credentials
4. Change the default password immediately!
5. Test creating a new user
6. Test logout/login
7. Test access levels

================================================================================
USER ROLES & PERMISSIONS
================================================================================

ADMIN:
- Full access to all features
- Can manage users
- Can view activity logs
- Can manage all data

MANAGER:
- Can manage clients, contacts, staff, introducers
- Cannot manage users
- Cannot view activity logs

USER:
- Can view and edit clients and contacts
- Limited access to management features

VIEWER:
- Read-only access
- Cannot create or edit records

================================================================================
SECURITY FEATURES EXPLAINED
================================================================================

PASSWORD SECURITY:
- Passwords hashed with bcrypt
- Minimum 8 characters required
- Password history tracking
- Last password change timestamp

ACCOUNT LOCKOUT:
- 5 failed attempts = 15 minute lockout
- Automatic reset after lockout period
- Failed attempts logged

SESSION MANAGEMENT:
- Secure session tokens
- 24-hour session expiration
- Remember me (30 days optional)
- Automatic session cleanup

ACTIVITY LOGGING:
- All user actions logged
- IP address tracking
- User agent recording
- Timestamp for all activities

================================================================================
FIRST TIME SETUP
================================================================================

After installation:

1. LOGIN AS ADMIN
   - Use credentials: admin / Admin@123

2. CHANGE ADMIN PASSWORD
   - Click your name (top right)
   - Select "Change Password"
   - Enter current: Admin@123
   - Enter new strong password
   - Save

3. CREATE YOUR USERS
   - Go to Management > Users
   - Click "Add New User"
   - Fill in details
   - Assign appropriate role
   - Give them temporary password
   - They should change it on first login

4. OPTIONAL: Delete or disable default manager account
   - If you don't need it

5. TEST PERMISSIONS
   - Logout
   - Login with new user
   - Verify access levels work

================================================================================
MANAGING USERS
================================================================================

TO ADD A USER:
1. Login as Admin
2. Management > Users
3. Fill in user details
4. Select role
5. Create user
6. Give user their credentials

TO CHANGE USER STATUS:
1. Management > Users
2. Click Edit on user
3. Change status (Active/Inactive/Suspended/Locked)
4. Save

TO RESET USER PASSWORD (as Admin):
1. Management > Users
2. Click Edit on user
3. Enter new password
4. Save
5. Inform user of new password

================================================================================
ACTIVITY LOG
================================================================================

Admins can view all user activity:
- Management > Activity Log
- See who did what and when
- Filter by user, action, date
- Export for auditing

Logged activities:
- Login/logout
- Create/edit/delete records
- Password changes
- User management
- Search queries

================================================================================
TROUBLESHOOTING
================================================================================

PROBLEM: Can't login - "Invalid username or password"
SOLUTION:
- Verify username is correct (case-sensitive)
- Check caps lock is off
- Try default credentials if first install
- Check user status is "Active"

PROBLEM: Account locked
SOLUTION:
- Wait 15 minutes
- Or ask admin to reset failed_login_attempts

PROBLEM: Redirected to login on every page
SOLUTION:
- Check sessions are enabled (php.ini)
- Verify cookies are enabled in browser
- Check session directory is writable

PROBLEM: Access denied to all pages
SOLUTION:
- Verify user role is correct
- Check user status is "Active"
- Logout and login again

PROBLEM: Can't see user management
SOLUTION:
- Only Admin role can access
- Verify your role: click your name in nav

================================================================================
SECURITY BEST PRACTICES
================================================================================

PASSWORDS:
✓ Require strong passwords (8+ chars)
✓ Include numbers and special characters
✓ Change default passwords immediately
✓ Change passwords every 90 days
✓ Don't reuse old passwords

USER MANAGEMENT:
✓ Only give necessary permissions
✓ Use principle of least privilege
✓ Disable inactive user accounts
✓ Review user list regularly
✓ Remove terminated users promptly

MONITORING:
✓ Review activity logs weekly
✓ Watch for suspicious login attempts
✓ Monitor failed login patterns
✓ Check for after-hours access
✓ Review user permission changes

DATABASE:
✓ Keep backups current
✓ Restrict database user permissions
✓ Use strong database password
✓ Enable SSL for database connections
✓ Keep MariaDB/MySQL updated

================================================================================
UPDATING EXISTING CODE
================================================================================

All existing pages now:
✓ Require login automatically
✓ Track who created/updated records
✓ Log user activities
✓ Respect role-based permissions

No changes needed to your existing client/contact/staff/introducer data.
The created_by/updated_by fields are added but start as NULL.

================================================================================
ADDITIONAL FILES (OPTIONAL)
================================================================================

You may want to create:
- forms/profile.php - User profile editing
- forms/activity_log.php - Activity log viewer
- forms/edit_user.php - Edit user details
- forgot_password.php - Password reset

These are not included but can be added later.

================================================================================
ROLLBACK INSTRUCTIONS
================================================================================

If you need to undo this update:

1. Restore database:
   mysql -u username -p investor_db < backup_v2.1_before_security.sql

2. Restore old header.php file

3. Delete authentication files:
   - includes/auth.php
   - login.php
   - logout.php
   - access_denied.php
   - forms/user_management.php
   - forms/change_password.php

================================================================================
VERSION INFORMATION
================================================================================

Version: 2.2 - Security & Authentication
Previous Version: 2.1 - Introducers & Ownership
Release: December 2024
Database Changes: Yes (4 new tables + columns)
Breaking Changes: YES - Requires login
Backward Compatible: No - All pages now require authentication

================================================================================
SUPPORT
================================================================================

For issues:
1. Check this installation guide
2. Verify all steps completed
3. Check PHP error logs
4. Contact system administrator

Common files to check:
- includes/auth.php (authentication logic)
- includes/header.php (login requirement)
- database/add_authentication.sql (DB structure)

================================================================================
POST-INSTALLATION CHECKLIST
================================================================================

□ Database updated successfully
□ Can access login page
□ Can login with admin credentials
□ Admin password changed from default
□ Manager password changed from default
□ Created at least one additional user
□ Tested user permissions
□ Tested logout
□ Tested change password
□ Activity log working (Admin)
□ User management working (Admin)
□ All pages require login
□ Access denied page works
□ Backup created

================================================================================
SYSTEM NOW SECURE
================================================================================

Your investor database is now protected with:
✓ Login authentication
✓ Role-based access control
✓ Activity logging
✓ Secure password storage
✓ Session management
✓ Failed login protection

All users must login to access any page.
All activities are logged.
All data is protected.

REMEMBER: Change default passwords immediately!

================================================================================
END OF INSTALLATION GUIDE
================================================================================
