Update README with security documentation

2025-12-10 10:46:57 +11:00
parent 446414da3e
commit 3a3e8e46aa
1 changed files with 145 additions and 81 deletions
--- a/README.md
+++ b/README.md
@@ -1,33 +1,46 @@
 # 🦝 Raccoon Timekeeper

-A self-hosted time tracking application with a sleek grayscale design.
-
-![Raccoon Timekeeper](https://img.shields.io/badge/version-1.0.0-gray)
-![Python](https://img.shields.io/badge/python-3.10+-blue)
-![License](https://img.shields.io/badge/license-MIT-green)
+A self-hosted time tracking application with multi-user support and role-based access control.

 ## Features

- ⏱️ **Flexible Time Entry** - Log time in multiple formats (1:30, 1.5, 90m, 1h 30m)
- 📅 **Weekly Summaries** - View time grouped by task and day (Monday-Sunday weeks)
- 🖨️ **Printable Timesheets** - Generate clean printable weekly reports
- 📋 **Task Management** - Create, edit, and organize your tasks
- 📊 **Data Export** - Export your data as JSON or CSV
- 🎨 **Raccoon Theme** - Sleek grayscale design
+- **Multi-user support** - Each user has their own tasks and time entries
+- **Role-based access** - Admin users can manage all users, regular users can only see their own data
+- **First-run setup** - Admin account created on first launch via web interface
+- **CLI management** - Reset admin password or create users from command line
+- **Weekly timesheets** - View and print weekly summaries
+- **Flexible time input** - Supports formats like `1:30`, `1.5`, `90m`, `1h 30m`
+- **Task management** - Each user manages their own task list

-## Quick Start
+## Security Model
+
+### User Isolation
+- Each user can only view and modify their own:
+  - Tasks
+  - Time entries
+  - Weekly summaries
+- All API endpoints filter by `current_user.id`
+
+### Admin Privileges
+Admin users can:
+- View all users
+- Create new users
+- Edit user details (email, display name, admin status)
+- Activate/deactivate user accounts
+- Reset user passwords
+- Delete users (and all their data)
+
+Admin users **cannot**:
+- Deactivate their own account
+- Remove their own admin status
+- Delete their own account
+
+## Installation

 ### Using Docker (Recommended)

 ```bash
-# Clone the repository
-git clone https://gitea.hideawaygaming.com.au/jessikitty/Raccoon-TimeKeeper.git
-cd Raccoon-TimeKeeper
-
-# Start with Docker Compose
 docker-compose up -d
-
-# Access at http://localhost:5000
 ```

 ### Manual Installation
@@ -39,89 +52,140 @@ cd Raccoon-TimeKeeper

 # Create virtual environment
 python -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
+source venv/bin/activate  # Linux/Mac
+# or: venv\Scripts\activate  # Windows

 # Install dependencies
 pip install -r requirements.txt

-# Copy environment file
-cp .env.example .env
+# Initialize database
+flask init-db

 # Run the application
-python app.py
-
-# Access at http://localhost:5000
+flask run --host=0.0.0.0 --port=5000
 ```

-## Configuration
+## First-Run Setup

-Create a `.env` file based on `.env.example`:
+1. Navigate to `http://localhost:5000`
+2. You'll be redirected to the setup page
+3. Create your admin account:
+   - Username (min 3 characters)
+   - Email
+   - Display name (optional)
+   - Password (min 8 characters)
+4. Log in with your new credentials

-```env
-SECRET_KEY=your-super-secret-key-change-me
-DATABASE_URL=sqlite:///data/timekeeper.db
-DEBUG=false
+## CLI Commands
+
+### Initialize Database
+```bash
+flask init-db
 ```

-## Time Entry Formats
+### Reset Admin Password
+If you're locked out, reset the admin account from the command line:
+```bash
+flask reset-admin
+```
+You'll be prompted for:
+- New admin username
+- New admin email
+- New password

-The time input field accepts multiple formats:
+This will either update the existing admin or create a new one if none exists.

-| Format | Example | Result |
-|--------|---------|--------|
-| Hours:Minutes | `1:30` | 1h 30m |
-| Decimal Hours | `1.5` | 1h 30m |
-| Minutes | `90m` | 1h 30m |
-| Hours | `2h` | 2h 0m |
-| Combined | `1h 30m` | 1h 30m |
+### Create User from CLI
+```bash
+flask create-user
+```
+Options:
+- `--admin` flag to make the user an administrator
+
+### List All Users
+```bash
+flask list-users
+```
+Shows all users with their status (active/inactive) and admin flag.
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SECRET_KEY` | Flask secret key for sessions | Auto-generated |
+| `DATABASE_URL` | Database connection string | `sqlite:///timekeeper.db` |
+| `DEBUG` | Enable debug mode | `false` |

 ## API Endpoints

-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/api/tasks` | Get all tasks |
-| POST | `/api/tasks` | Create a task |
-| PUT | `/api/tasks/<id>` | Update a task |
-| DELETE | `/api/tasks/<id>` | Delete a task |
-| GET | `/api/entries` | Get all time entries |
-| POST | `/api/entries` | Create a time entry |
-| PUT | `/api/entries/<id>` | Update a time entry |
-| DELETE | `/api/entries/<id>` | Delete a time entry |
-| GET | `/api/weekly-summary` | Get weekly summary |
+### Authentication
+- `GET /login` - Login page
+- `POST /login` - Process login
+- `GET /logout` - Logout user
+- `GET /setup` - First-run admin setup
+- `GET /change-password` - Change password page

-## Project Structure
+### Pages (require login)
+- `GET /` - Main time logging page
+- `GET /settings` - Task management
+- `GET /admin/users` - User management (admin only)

-```
-raccoon-timekeeper/
-├── app.py              # Main Flask application
-├── requirements.txt    # Python dependencies
-├── Dockerfile          # Docker build file
-├── docker-compose.yml  # Docker Compose config
-├── .env.example        # Example environment file
-├── templates/          # HTML templates
-│   ├── base.html
-│   ├── index.html
-│   └── settings.html
-└── static/
-    ├── css/
-    │   └── style.css   # Raccoon grayscale theme
-    └── js/
-        ├── app.js      # Shared utilities
-        ├── index.js    # Index page logic
-        └── settings.js # Settings page logic
-```
+### Tasks API (user-scoped)
+- `GET /api/tasks` - List user's tasks
+- `POST /api/tasks` - Create task
+- `PUT /api/tasks/<id>` - Update task
+- `DELETE /api/tasks/<id>` - Delete task

-## Development
+### Entries API (user-scoped)
+- `GET /api/entries` - List user's entries
+- `POST /api/entries` - Create entry
+- `PUT /api/entries/<id>` - Update entry
+- `DELETE /api/entries/<id>` - Delete entry
+- `GET /api/weekly-summary` - Get weekly summary

-```bash
-# Run in debug mode
-DEBUG=true python app.py
-```
+### Admin API (admin only)
+- `GET /api/admin/users` - List all users
+- `POST /api/admin/users` - Create user
+- `PUT /api/admin/users/<id>` - Update user
+- `DELETE /api/admin/users/<id>` - Delete user
+
+## Database Schema
+
+### Users
+| Column | Type | Description |
+|--------|------|-------------|
+| id | Integer | Primary key |
+| username | String(80) | Unique username |
+| email | String(120) | Unique email |
+| password_hash | String(256) | Hashed password |
+| display_name | String(100) | Display name |
+| is_admin | Boolean | Admin flag |
+| is_active | Boolean | Account active |
+| created_at | DateTime | Creation timestamp |
+| last_login | DateTime | Last login time |
+
+### Tasks
+| Column | Type | Description |
+|--------|------|-------------|
+| id | Integer | Primary key |
+| user_id | Integer | Owner (FK to users) |
+| name | String(100) | Task name |
+| active | Boolean | Active flag |
+| created_at | DateTime | Creation timestamp |
+
+### Time Entries
+| Column | Type | Description |
+|--------|------|-------------|
+| id | Integer | Primary key |
+| user_id | Integer | Owner (FK to users) |
+| task_id | Integer | Task (FK to tasks) |
+| date | Date | Entry date |
+| hours | Integer | Hours component |
+| minutes | Integer | Minutes component |
+| total_minutes | Integer | Total in minutes |
+| notes | String(500) | Optional notes |
+| created_at | DateTime | Creation timestamp |

 ## License

-MIT License - feel free to use and modify!
-
---
-
-Made with 🦝 by Raccoon Timekeeper
+MIT License