Release v5.20.0

.do/deploy.template.yaml

@@ -0,0 +1,53 @@
+# DigitalOcean App Platform — Deploy to DigitalOcean button
+# https://docs.digitalocean.com/products/app-platform/how-to/add-deploy-do-button/
+#
+# Uses the public Docker Hub image (same multi-arch build as GHCR).
+# Dev Database only (Deploy button limitation). For production, use a managed
+# Postgres cluster or self-host with docker-compose.nas.yml.
+#
+# Button: https://cloud.digitalocean.com/apps/new?repo=https://github.com/DRYTRIX/TimeTracker/tree/develop
+# (default branch; switch to /tree/main after the template is merged to main)
+
+spec:
+  name: timetracker
+  services:
+    - name: web
+      image:
+        registry_type: DOCKER_HUB
+        registry: drytrix
+        repository: timetracker
+        tag: latest
+      instance_count: 1
+      instance_size_slug: basic-xxs
+      http_port: 8080
+      health_check:
+        http_path: /_health
+        initial_delay_seconds: 30
+        period_seconds: 15
+        timeout_seconds: 10
+        success_threshold: 1
+        failure_threshold: 5
+      envs:
+        - key: FLASK_ENV
+          scope: RUN_TIME
+          value: production
+        - key: FLASK_APP
+          scope: RUN_TIME
+          value: app:create_app()
+        - key: AUTH_METHOD
+          scope: RUN_TIME
+          value: local
+        - key: REDIS_ENABLED
+          scope: RUN_TIME
+          value: "false"
+        - key: SECRET_KEY
+          scope: RUN_TIME
+          type: SECRET
+          # Replace at deploy time: openssl rand -hex 32
+          value: "CHANGE_ME_openssl_rand_hex_32"
+        - key: DATABASE_URL
+          scope: RUN_TIME
+          value: ${timetracker-db.DATABASE_URL}
+  databases:
+    - name: timetracker-db
+      engine: PG

.github/codeql/timetracker-python-models/models/sanitizers.yml

@@ -4,6 +4,7 @@ extensions:
       extensible: barrierModel
     data:
       - ["app.utils.safe_redirect", "Member[safe_redirect_target].ReturnValue", "url-redirection"]
+      - ["app.utils.safe_redirect", "Member[match_registered_redirect].ReturnValue", "url-redirection"]
       - ["app.utils.safe_redirect", "Member[_rebuild_relative].ReturnValue", "url-redirection"]
       - ["app.utils.safe_redirect", "Member[_rebuild_same_host].ReturnValue", "url-redirection"]
       - ["app.utils.error_handling", "Member[sanitize_log_value].ReturnValue", "log-injection"]

.github/dependabot.yml

@@ -13,6 +13,10 @@ updates:
     labels:
       - dependencies
       - python
+    # Gunicorn 26 removed the eventlet worker used by docker/start-fixed.py.
+    ignore:
+      - dependency-name: gunicorn
+        update-types: ["version-update:semver-major"]
 
   - package-ecosystem: npm
     directory: /
@@ -73,6 +77,10 @@ updates:
     labels:
       - dependencies
       - mobile
+    # Riverpod 3 removed StateNotifier; stay on 2.x until providers are migrated.
+    ignore:
+      - dependency-name: flutter_riverpod
+        update-types: ["version-update:semver-major"]
 
   - package-ecosystem: github-actions
     directory: /

.github/workflows/build-mobile.yml

@@ -112,6 +112,11 @@ jobs:
         working-directory: mobile
         run: flutter test
 
+      - name: Install CocoaPods deps
+        working-directory: mobile/ios
+        run: |
+          pod install --repo-update
+
       - name: Build iOS (simulator)
         working-directory: mobile
         env:

.github/workflows/cd-release.yml

@@ -854,6 +854,11 @@ jobs:
         working-directory: mobile
         run: flutter test
 
+      - name: Install CocoaPods deps
+        working-directory: mobile/ios
+        run: |
+          pod install --repo-update
+
       # Release mode is invalid for iOS simulator; this validates compilation and produces Runner.app for the artifact zip.
       - name: Build iOS (simulator)
         working-directory: mobile
@@ -1073,7 +1078,7 @@ jobs:
           cat RELEASE_NOTES.md
 
       - name: Create draft GitHub Release
-        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64  # v3.0.3
+        uses: softprops/action-gh-release@8a0cd651e5b2365bd640854a3fa5dfc70e4875f3  # v3.0.4
         with:
           tag_name: ${{ needs.determine-version.outputs.version }}
           name: Release ${{ needs.determine-version.outputs.version }}

.github/workflows/ci.yml

@@ -184,6 +184,9 @@ jobs:
             app/utils/integration_http.py
       - name: Silent exception ratchet
         run: python scripts/check_silent_excepts.py
+      - name: Route file size guard (soft)
+        run: python scripts/ci/check_route_file_sizes.py
+        continue-on-error: true
       - name: Translation coverage
         run: python scripts/check_translation_coverage.py
       - name: Version consistency

.github/workflows/migration-validate.yml

@@ -63,11 +63,16 @@ jobs:
       - name: Check for migration changes
         id: migration_check
         env:
-          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          # PRs use the PR base; pushes use the previous tip (github.event.before).
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
         run: |
-          # Compare against the PR base (not HEAD~1) so multi-commit PRs are covered
+          # All-zero "before" means first push / force-push with no prior tip.
+          if [ "${BASE_SHA:-}" = "0000000000000000000000000000000000000000" ]; then
+            BASE_SHA=""
+          fi
+          # Compare against the PR/push base (not HEAD~1) so multi-commit ranges are covered
           if [ -z "$BASE_SHA" ]; then
-            echo "⚠️ No PR base SHA; falling back to HEAD~1"
+            echo "⚠️ No PR/push base SHA; falling back to HEAD~1"
             DIFF_RANGE="HEAD~1"
           else
             DIFF_RANGE="${BASE_SHA}...HEAD"
@@ -88,16 +93,21 @@ jobs:
           DATABASE_URL: postgresql+psycopg2://test_user:test_password@localhost:5432/test_db
           FLASK_APP: app.py
           FLASK_ENV: testing
-          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
         run: |
           set -euo pipefail
 
+          # All-zero "before" means first push / force-push with no prior tip.
+          if [ "${BASE_SHA:-}" = "0000000000000000000000000000000000000000" ]; then
+            BASE_SHA=""
+          fi
+
           echo "🔍 Validating migration consistency..."
           echo "Current directory: $(pwd)"
           echo "Migration files:"
           ls -la migrations/versions/ | tail -5
 
-          # Ensure PR base commit is available for checkout (fork PRs / shallow edges)
+          # Ensure PR/push base commit is available for checkout (fork PRs / shallow edges)
           if [ -n "${BASE_SHA:-}" ]; then
             git fetch --no-tags --depth=1 origin "$BASE_SHA" 2>/dev/null || git fetch --no-tags origin "$BASE_SHA" || true
           fi

.gitignore

@@ -169,6 +169,7 @@ junit.xml
 *.xml
 !mobile/android/app/src/main/AndroidManifest.xml
 !templates/unraid/*.xml
+!ca_profile.xml
 test-results/
 .pytest_tmp*/
 bandit-report.json

.safety-policy.yml

@@ -10,5 +10,11 @@ security:
   ignore-unpinned-requirements: false
   ignore-cvss-severity-below: 0
   ignore-cvss-unknown-severity: false
-  ignore-vulnerabilities: {}
+  ignore-vulnerabilities:
+    # No fixed 3.x release yet (advisory range <3.12; latest is 3.11.3). We use the
+    # default MemoryJobStore only — not Redis/Mongo/SQLAlchemy stores that pickle
+    # job_state — so the persistent job-store deserialization path does not apply.
+    SFTY-20261008-90293:
+      reason: APScheduler MemoryJobStore only; no fixed 3.x release available
+      expires: '2027-05-01'
   continue-on-vulnerability-error: false

CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.20.0] - 2026-11-10
+### Added
+
+- **Enterprise identity** — OAuth 2.0 API apps (authorization code + PKCE, admin CRUD), SAML 2.0 login, SCIM Users provisioning, and shared Slack/Teams timer bot commands.
+- **Bank reconciliation & payroll** — Bank reconciliation workflows plus payroll/labor export APIs and UI.
+- **Inventory** — Stock locations, purchase-order email, and stock-levels CSV export.
+- **Invoicing** — XRechnung export and PDF QR/barcode elements on invoice/quote layouts.
+- **Peppol bridge: Let’s Peppol + inbox** — `PEPPOL_BRIDGE_PROVIDER=letspeppol` for Belgian access-point delivery, plus inbound Peppol inbox poll/ack in the bridge and admin UI.
+- **Kanban & custom fields** — Enforce kanban WIP limits; extend custom fields coverage.
+- **Clients** — Mobile sync retry backoff and failed-sync screen; desktop failed offline-sync surfacing and broader i18n; browser extension 2FA login, Firefox packaging, and tab URL suggestions.
+- **DigitalOcean one-click** — `.do/deploy.template.yaml` (Docker Hub image + Dev Database) and Deploy to DigitalOcean button in the README / Distribution guide.
+- **Unraid CA profile** — Root `ca_profile.xml` (`CommunityApplications` + `<Profile>`) required for Community Applications submission.
+
+### Security
+
+- **CodeQL** — Clear open redirect, stack-trace, weak-hashing, and XML-related alerts on develop paths used by auth/OAuth and related utilities.
+
+### Fixed
+
+- **Invoices** — Generating an invoice from many time entries no longer fails on PostgreSQL: `invoice_items.time_entry_ids` is now `TEXT` (was `VARCHAR(500)`).
+- **Report export** — CSV and Excel exports from the report form now apply the client, task, billable, source and tags filters.
+- **Payments** — Stripe checkout now sends JPY and other zero-decimal currencies (and three-decimal ones such as KWD) in the unit Stripe expects; before, every amount was multiplied by 100, so a JPY invoice was charged 100 times its balance, and the webhook amount was divided by 100 the same way.
+- **Peppol** — The UBL invoice now reports payments already recorded on the invoice as `PrepaidAmount` and sets `PayableAmount` to the total minus those payments (BR-CO-16), never below zero, as the Factur-X/ZUGFeRD export already does; before, a partly paid invoice sent or exported as UBL asked the buyer for the full total.
+- **CI / Docker** — Restore gunicorn 25.x (eventlet worker) after a major bump broke image boot; isolate setup-wizard fixture state; use push `before` SHA for migration drift; keep mobile on Riverpod 2.x.
+
+### Changed
+
+- **Mobile Android** — Bump Gradle wrapper to 8.14 so Flutter 3.47 release builds satisfy the minimum Gradle version.
+- **Dependencies** — Pip, Actions, npm (root + desktop), and Flutter mobile dependency bumps (with Dependabot major ignores for gunicorn and flutter_riverpod).
+
+### Documentation
+
+- **OrcaRouter** — AI Helper docs and Admin settings include a signup link for an OrcaRouter API key (`https://www.orcarouter.ai/ref/ref_984e584cb4cd86485a8c`).
+- **Deploy & discovery** — DigitalOcean and Railway deploy guides; Unraid CA + directory listing submission packages; publishing checklist (`docs/deploy/*`, `docs/marketing/*`).
+- **Gap roadmap** — Archive stale gap analyses; Phase 6 marked done for the implementation pass.
+
 ## [5.19.1] - 2026-11-07
 ### Added
 

Dockerfile

@@ -63,6 +63,11 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
     # Fonts
     fonts-liberation \
     fonts-dejavu-core \
+    # python3-saml / xmlsec (SAML SSO — see docs/design/SAML_SCIM.md)
+    libxml2-dev \
+    libxmlsec1-dev \
+    libxmlsec1-openssl \
+    pkg-config \
     # PostgreSQL client dependencies
     gnupg \
     wget \

Makefile

@@ -2,7 +2,8 @@
 # Common development and testing tasks
 
 .PHONY: help install test test-smoke test-unit test-integration test-security test-coverage \
-        test-fast test-parallel lint format clean docker-build docker-run setup dev security-scan frontend-a11y
+        test-fast test-parallel lint format clean docker-build docker-run setup dev security-scan frontend-a11y \
+        check-route-sizes
 
 # Default target
 help:
@@ -33,6 +34,7 @@ help:
 	@echo "  make lint           - Run linters (flake8)"
 	@echo "  make format         - Format code (black + isort)"
 	@echo "  make format-check   - Check code formatting"
+	@echo "  make check-route-sizes - Soft route file line-count guard (warn >2000, fail >2500)"
 	@echo "  make security-scan  - Run security scanners"
 	@echo "  make frontend-a11y  - Run accessibility check on web app (requires app running; set FRONTEND_URL)"
 	@echo ""
@@ -113,6 +115,10 @@ lint:
 	flake8 app/ --count --select=E9,F63,F7,F82 --show-source --statistics
 	flake8 app/ --count --max-complexity=10 --max-line-length=120 --statistics
 
+check-route-sizes:
+	@echo "Checking app/routes/*.py line counts..."
+	python3 scripts/ci/check_route_file_sizes.py
+
 format:
 	@echo "Running black..."
 	black app/

README.md

@@ -34,7 +34,7 @@ docker compose -f docker-compose.nas.yml up -d
 # open http://localhost:8080 — first login creates the admin
 ```
 
-**Latest release: v5.19.1** — see [CHANGELOG.md](CHANGELOG.md).
+**Latest release: v5.20.0** — see [CHANGELOG.md](CHANGELOG.md).
 
 ### First 5 minutes
 
@@ -152,11 +152,11 @@ Timers, projects, clients, CRM pipeline, PDF + Peppol invoicing, expenses, repor
 | **NAS compose** | QNAP, Synology, Portainer | Paste [`docker-compose.nas.yml`](docker-compose.nas.yml) — [NAS guide](docs/admin/deployment/NAS_DEPLOYMENT.md) |
 | **GitHub Release** | Compose files + desktop/mobile | [Releases](https://github.com/drytrix/TimeTracker/releases) |
 | **Cloud (Render)** | Managed hosting | [![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/drytrix/TimeTracker) |
+| **Cloud (DigitalOcean)** | Managed hosting | [![Deploy to DigitalOcean](https://www.deploytodo.com/do-btn-blue.svg)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/DRYTRIX/TimeTracker/tree/develop) |
 | **Railyard** | Managed hosting | [![Deploy to Railyard](https://app.railyard.run/deploy/badge)](https://app.railyard.run/deploy?repo=https://github.com/DRYTRIX/TimeTracker) |
 | **Cloud (RepoCloud)** | Managed hosting | <a href="https://repocloud.io/details/TimeTracker/"><img src="https://d16t0pc4846x52.cloudfront.net/deploylobe.svg" alt="Deploy on RepoCloud" height="32"></a> |
 
-
-**Full list of install paths:** [Distribution Guide](docs/admin/deployment/DISTRIBUTION.md) (Portainer templates, Unraid, Railway, Fly.io, Coolify, [Docker Hub](https://hub.docker.com/r/drytrix/timetracker))
+**Full list of install paths:** [Distribution Guide](docs/admin/deployment/DISTRIBUTION.md) (Portainer templates, Unraid, Railway, Fly.io, Coolify, DigitalOcean, [Docker Hub](https://hub.docker.com/r/drytrix/timetracker))
 
 > **Docker Hub namespace:** images are published at [`drytrix/timetracker`](https://hub.docker.com/r/drytrix/timetracker) (formerly `driesp/timetracker`).
 
@@ -343,6 +343,7 @@ Comprehensive documentation is available in the [`docs/`](docs/) directory. See
 - **[Task Management](docs/TASK_MANAGEMENT_README.md)** — Task tracking system
 - **[Client Management](docs/CLIENT_MANAGEMENT_README.md)** — Client relationships
 - **[Invoice System](docs/INVOICE_FEATURE_README.md)** — Invoice generation
+- **[Overdue reminders & recurring invoices](docs/features/INVOICE_REMINDERS_AND_RECURRING.md)** — Daily overdue check and recurring billing
 
 **Advanced Features:**
 - **[Calendar & Bulk Entry](docs/CALENDAR_FEATURES_README.md)** — Calendar view and bulk operations
@@ -439,6 +440,7 @@ TimeTracker includes an optional **server-side AI helper** for the web app and A
 
 - **Enable (any setup)**: set `AI_ENABLED=true` (environment or **Admin → System Settings → AI Helper**).
 - **Ollama**: set `AI_PROVIDER=ollama`, `AI_MODEL=...`, and `AI_BASE_URL` to `http://ollama:11434` when Ollama runs in Docker on the same Compose network, or `http://127.0.0.1:11434` when Ollama runs on the host.
+- **OrcaRouter** (hosted multi-model gateway): set `AI_PROVIDER=orcarouter`, `AI_BASE_URL=https://api.orcarouter.ai`, and `AI_API_KEY=...`. [Sign up for an API key](https://www.orcarouter.ai/ref/ref_984e584cb4cd86485a8c).
 - **Hosted OpenAI-compatible**: set `AI_PROVIDER=openai_compatible` and `AI_API_KEY=...`
 
 The AI helper is exposed as:
@@ -472,7 +474,7 @@ The root `docker-compose.yml` defines a CPU-only **`ollama`** service and a one-
 - Pulled models are cached in the `ollama_data` named volume, so subsequent boots are faster.
 - Verify in the UI: **Admin → System Settings → AI helper**, then click *Test connection*.
 - To pull additional models manually: `docker compose exec ollama ollama pull <model>` (with the `ai` profile active).
-- **Hosted provider only (no Ollama containers):** set `AI_PROVIDER=openai_compatible`, `AI_BASE_URL`, and `AI_API_KEY` in `.env`; keep `docker compose up -d` without the `ai` profile.
+- **Hosted provider only (no Ollama containers):** set `AI_PROVIDER=orcarouter` (or `openai_compatible`), `AI_BASE_URL`, and `AI_API_KEY` in `.env`; keep `docker compose up -d` without the `ai` profile. For OrcaRouter, [sign up here](https://www.orcarouter.ai/ref/ref_984e584cb4cd86485a8c).
 
 **Disable or remove AI** (turn off LLM calls, stop Ollama, revoke tokens, delete `ollama_data` safely): [UNINSTALL.md](UNINSTALL.md#disabling-or-removing-the-ai-helper).
 

VERSION

@@ -1 +1 @@
-5.19.1
+5.20.0