# User Management Quick Start

## Installation Complete ✓

The user management system has been installed and configured.

## Quick Test

```bash
# Start the application
mix deps.get
sudo mix run --no-halt

# In another terminal or IEx
iex -S mix

# Run the demo
iex> UserExamples.demo()

# Or run quick test
iex> UserExamples.quick_test()
```

## Create Your First User

```elixir
# In IEx
iex> User.create("admin", "admin@example.com", "YourSecurePassword123", [123456, 11111])
{:ok, 1738265123456}
```

## User Table Schema

```
users table:
├── id                      - Auto-generated unique ID
├── username                - Unique login name
├── email                   - Unique email
├── password_hash           - Argon2 hashed password
├── permission_keys         - JSON array [123456, 11111]
├── created_at              - Account creation timestamp
├── updated_at              - Last update (optimistic locking)
├── last_login_at           - Last successful login
├── last_login_ip           - IP of last login
├── failed_login_attempts   - Failed login counter
├── locked_until            - Lock expiration timestamp
├── is_active               - 1=active, 0=disabled
├── session_token           - Hashed session token
├── session_expires_at      - Session expiration
├── password_changed_at     - Last password change
├── must_change_password    - Force change flag
├── two_factor_enabled      - 2FA enabled flag
├── two_factor_secret       - 2FA secret (encrypted)
└── metadata                - JSON for custom data

user_audit_log table:
├── id                      - Log entry ID
├── user_id                 - FK to users
├── action                  - Event type
├── details                 - JSON event details
├── ip_address              - Source IP
├── user_agent              - Browser/client info
├── created_at              - Event timestamp
└── updated_at              - Update timestamp
```

## Permission Keys

Map permission keys to named permissions in `lib/auth/authorization.ex`:

```elixir
@permissions %{
  "index:view" => 123456,
  "admin:manage" => 11111
}
```

## Essential Functions

```elixir
# Create user
User.create(username, email, password, permission_keys)

# Authenticate
User.authenticate(username, password, ip_address)

# Session management
User.create_session(user_id)
User.validate_session(session_token)
User.clear_session(user_id)

# Permissions
User.get_permissions(user_id)
User.add_permissions(user_id, [123456])
User.remove_permissions(user_id, [11111])

# Password management
User.change_password(user_id, old_pass, new_pass)
User.reset_password(user_id, new_pass)

# Account management
User.activate_account(user_id)
User.deactivate_account(user_id)
User.unlock_account(user_id)

# Audit
User.get_audit_log(user_id, limit: 50)
```

## Security Settings

In `lib/user.ex`:

```elixir
@max_failed_attempts 5              # Lock after 5 failures
@lockout_duration_seconds 900       # 15 minute lockout
@session_duration_seconds 86400     # 24 hour sessions
```

## Files Created

```
lib/
├── user.ex                        - Main user management module
└── user_examples.ex               - Usage examples

docs/
├── USER_MANAGEMENT.md             - Complete documentation
└── USER_QUICK_START.md            - This file

mix.exs
└── Added: {:argon2_elixir, "~> 4.0"}

lib/mcp/application.ex
└── Added: {Sqler, name: "users", register: :users_db}
```

## Database Location

```
data/users.sqlite   - User database file
```

## Security Features

✅ Argon2 password hashing (OWASP recommended)
✅ Encrypted session tokens
✅ Account lockout after failed attempts
✅ Session expiration
✅ Complete audit logging
✅ Permission-based authorization
✅ Password complexity validation
✅ 2FA ready (schema includes fields)

## Next Steps

1. **Test the system**: Run `UserExamples.demo()`
2. **Create admin user**: Use `User.create(...)`
3. **Integrate with router**: See `docs/USER_MANAGEMENT.md` Integration section
4. **Configure security**: Adjust settings in `lib/user.ex`
5. **Add your permissions**: Update `lib/auth/authorization.ex`

## Integration with Router

Update `lib/my_mcp_server_router.ex`:

```elixir
defp get_user(conn) do
  conn = fetch_cookies(conn)

  case conn.cookies["user"] do
    nil -> %{id: 0, keys: %{}}
    encrypted ->
      case decrypt_cookie_value(encrypted) do
        {:ok, user_id_str} ->
          user_id = String.to_integer(user_id_str)

          # Load from database instead of hardcoded map
          case User.get_user(user_id) do
            {:ok, db_user} ->
              # Convert permission keys list to map
              keys_map = db_user.permission_keys
              |> Enum.map(&{&1, true})
              |> Map.new()

              %{id: db_user.id, keys: keys_map, username: db_user.username}

            {:error, _} ->
              %{id: 0, keys: %{}}
          end

        {:error, _} ->
          %{id: 0, keys: %{}}
      end
  end
end
```

## Full Documentation

See `docs/USER_MANAGEMENT.md` for:
- Complete API reference
- Security best practices
- Integration examples
- Troubleshooting guide
- Migration from old system

## Support

Module documentation:
```elixir
iex> h User
iex> h User.create
iex> h User.authenticate
```

## Example Session

```elixir
# Create user
{:ok, user_id} = User.create("alice", "alice@example.com", "SecurePass123", [123456])

# Login
{:ok, user} = User.authenticate("alice", "SecurePass123", "192.168.1.100")

# Create session
{:ok, token} = User.create_session(user_id)

# Store token in cookie (in router)
put_resp_cookie("session", token, secure: true, http_only: true)

# Later: validate session
{:ok, user} = User.validate_session(token)

# Check permissions
{:ok, perms} = User.get_permissions(user_id)
# => [123456]

# View audit log
User.get_audit_log(user_id) |> Enum.take(5)
```

That's it! Your user management system is ready to use. 🎉