From 3a3e8e46aa2636c21ce35fede50be161d2737566 Mon Sep 17 00:00:00 2001 From: jessikitty Date: Wed, 10 Dec 2025 10:46:57 +1100 Subject: [PATCH] Update README with security documentation --- README.md | 226 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 145 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index fa14d7b..ac27e46 100644 --- 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/` | Update a task | -| DELETE | `/api/tasks/` | Delete a task | -| GET | `/api/entries` | Get all time entries | -| POST | `/api/entries` | Create a time entry | -| PUT | `/api/entries/` | Update a time entry | -| DELETE | `/api/entries/` | 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/` - Update task +- `DELETE /api/tasks/` - Delete task -## Development +### Entries API (user-scoped) +- `GET /api/entries` - List user's entries +- `POST /api/entries` - Create entry +- `PUT /api/entries/` - Update entry +- `DELETE /api/entries/` - 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/` - Update user +- `DELETE /api/admin/users/` - 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