euchre_camp/docs/AAA_DESIGN.md

Authentication, Authorization, and Accounting (AAA) Design

Overview

Implement a comprehensive AAA system for EuchreCamp with user authentication, role-based authorization, and activity logging.

Authentication (Who are you?)

User Model

# Database Schema
table :users do
  primary_key :id
  foreign_key :player_id, :players  # Links to existing player record
  column :email, String, null: false, unique: true
  column :password_digest, String, null: false
  column :confirmed, Boolean, default: false
  column :confirmation_token, String
  column :confirmation_sent_at, DateTime
  column :reset_password_token, String
  column :reset_password_sent_at, DateTime
  column :failed_login_attempts, Integer, default: 0
  column :locked_until, DateTime
  column :last_login_at, DateTime
  column :last_login_ip, String
  column :created_at, DateTime, null: false
  column :updated_at, DateTime, null: false
end

# Indexes
add_index :users, :email, unique: true
add_index :users, :confirmation_token
add_index :users, :reset_password_token

Authentication Flow

1. User enters email and password
2. System verifies email exists and account is not locked
3. BCrypt verifies password hash
4. If successful:
   • Update last_login_at and last_login_ip
   • Reset failed_login_attempts
   • Create session/token
5. If failed:
   • Increment failed_login_attempts
   • Lock account after 5 failed attempts (15 minutes)

Session Management

• Use signed cookies for session storage
• Session expires after 30 days of inactivity
• Session invalidation on password change
• Concurrent session limits (optional)

Password Requirements

• Minimum 8 characters
• At least one uppercase letter
• At least one lowercase letter
• At least one number
• At least one special character

Registration Flow

1. User registers with email and password
2. System creates user record with confirmed: false
3. Send confirmation email with unique token
4. User clicks link to confirm account
5. Account activated and ready for login

Password Reset Flow

1. User requests password reset
2. System generates unique token (expires in 1 hour)
3. Send reset email with token link
4. User enters new password
5. System validates and updates password hash
6. Invalidate all existing sessions

Authorization (What can you do?)

Role-Based Access Control (RBAC)

Roles

ROLES = {
  player: 0,      # Default user - can view rankings, own profile
  tournament_admin: 1,  # Can manage specific tournaments
  club_admin: 2,        # Superuser - full access
  system_admin: 3       # Technical admin access
}

Permission Matrix

Permission	Player	Tournament Admin	Club Admin	System Admin
View rankings	✅	✅	✅	✅
View own profile	✅	✅	✅	✅
Edit own profile	✅	✅	✅	✅
View other profiles	✅	✅	✅	✅
Record own matches	✅	✅	✅	✅
Create tournaments	❌	✅	✅	✅
Manage own tournaments	❌	✅	✅	✅
Manage all tournaments	❌	❌	✅	✅
Manage all players	❌	❌	✅	✅
Club settings	❌	❌	✅	✅
System settings	❌	❌	❌	✅

Implementation

module EuchreCamp
  module Auth
    class Authorization
      def self.can?(user, action, resource = nil)
        case action
        when :view_rankings
          true  # All users can view rankings
        when :edit_profile
          resource.nil? || resource.id == user.player_id
        when :create_tournament
          user.club_admin? || user.system_admin?
        when :manage_tournament
          user.club_admin? || user.system_admin? || 
          (user.tournament_admin? && resource.admin_id == user.player_id)
        when :manage_players
          user.club_admin? || user.system_admin?
        else
          false
        end
      end
    end
  end
end

Middleware

• Authentication middleware checks for valid session
• Authorization middleware verifies permissions
• Redirect unauthenticated users to login
• Show 403 Forbidden for unauthorized actions

Accounting (What did you do?)

Activity Logging

table :activity_logs do
  primary_key :id
  foreign_key :user_id, :users
  column :action, String, null: false  # e.g., 'login', 'create_tournament', 'record_match'
  column :resource_type, String        # e.g., 'tournament', 'match', 'player'
  column :resource_id, Integer
  column :ip_address, String
  column :user_agent, String
  column :details, JSON                # Additional context
  column :created_at, DateTime, null: false
end

add_index :activity_logs, [:user_id, :created_at]
add_index :activity_logs, [:resource_type, :resource_id]

Tracked Events

• Authentication events (login, logout, password change)
• Tournament management (create, update, delete, schedule)
• Match recording (create, update, delete)
• Player management (create, update)
• Settings changes

Audit Reports

• User activity timeline
• Tournament lifecycle audit
• Match result verification log
• System changes overview

Implementation Plan

Phase 1: Authentication (Week 1-2)

• Create users table and model
• Implement BCrypt password hashing
• Build login/logout actions
• Create registration flow
• Add session management
• Password reset functionality

Phase 2: Authorization (Week 2-3)

• Define roles and permissions
• Implement RBAC middleware
• Add role assignment UI (for club admins)
• Protect routes based on roles
• Add permission checks to actions

Phase 3: Accounting (Week 3-4)

• Create activity logging system
• Track key events
• Build audit reports UI
• Add activity feed to dashboard

Phase 4: Security Hardening (Week 4-5)

• Rate limiting on login attempts
• IP-based lockout
• Secure cookie settings
• CSRF protection
• Security headers
• Session fixation prevention

Security Considerations

Password Security

• Use BCrypt with cost factor 12+
• Never store plaintext passwords
• Enforce strong password policy
• Rate limit password attempts

Session Security

• Use signed, encrypted cookies
• Regenerate session ID on privilege escalation
• Set appropriate expiration times
• Invalidate on password change

Access Control

• Principle of least privilege
• Defense in depth
• Fail securely (deny by default)
• Log all access attempts

Data Protection

• Encrypt sensitive data at rest
• Secure transmission (HTTPS only)
• Regular security audits
• Compliance with privacy regulations

API Endpoints

Authentication

POST /auth/login       # Login with email/password
POST /auth/logout      # Logout current session
POST /auth/register    # Create new account
POST /auth/confirm     # Confirm email address
POST /auth/forgot      # Request password reset
POST /auth/reset       # Reset password with token

Users

GET  /users/me         # Get current user profile
PATCH /users/me        # Update own profile
GET  /users/:id        # Get user profile (public)

Admin

GET  /admin/users      # List users (club admin only)
PATCH /admin/users/:id # Update user roles (club admin only)
GET  /admin/activity   # View audit logs (club admin only)

Testing Strategy

Unit Tests

• Password hashing verification
• Permission calculations
• Session management
• Activity logging

Integration Tests

• Login/logout flow
• Registration process
• Password reset
• Role-based access

Security Tests

• SQL injection prevention
• XSS prevention
• CSRF protection
• Rate limiting
• Session security

Migration Steps

1. Create users table and related migrations
2. Add foreign key from users to players
3. Migrate existing player data to users (optional)
4. Update navigation to show login/logout links
5. Add authentication checks to existing actions
6. Implement role assignment for existing admins
7. Set up activity logging for new features