feat: enforce app-admin role gating and update docs

Restrict app administration to an optional allowlist of Nextcloud admins with middleware-based enforcement and clear 403 handling. Document the new admin setup flow and add focused Docker security test commands for role-gating verification.

Made-with: Cursor

Author: aSoftwareByDesignRepository

CHANGELOG.de.md

@@ -1,5 +1,33 @@
 ## [Unreleased]
 
+### Hinzugefügt
+
+- **Monatsabschluss: Karenz und Auto-Finalisierung**: Admin-Einstellung `month_closure_grace_days_after_eom` (0–90, Standard 0). Nach Monatsende haben Mitarbeitende so viele Kalendertage zur manuellen Finalisierung; ist der Monat danach noch offen, finalisiert ein täglicher Hintergrundauftrag automatisch (gleicher Snapshot wie manuell). Ausstehende Zeiteintragsfreigaben und offene Abwesenheits-Workflows blockieren die Auto-Finalisierung. Wiederöffnen bleibt Administrator:innen vorbehalten.
+- **App-Admin-Whitelist**: Neue Admin-Einstellung `app_admin_user_ids`, um die Administration von ArbeitszeitCheck auf eine ausgewählte Teilmenge der Nextcloud-Admins zu begrenzen. Leere Auswahl bleibt rückwärtskompatibel (alle Nextcloud-Admins dürfen die App verwalten).
+- **Docker-Testziel für Security-Role-Gating**: Verdrahtung von `scripts/test-security-role-gating-docker.sh` über `make test-security-role-gating-docker` und `composer test:security-role-gating:docker` für schnelle Autorisierungs-Regressionstests im Container-Setup.
+
+### Geändert
+
+- **Monatsabschluss UX/API**: Klarere Karten-UI, sichtbares Erfolgs-/Fehlerfeedback (WCAG), serverseitiges `canFinalize` mit lokalisierten Sperrgründen; manuelle Finalisierung lehnt zukünftige Kalendermonate ab; Abwesenheits-Workflow (`pending`, `substitute_pending`, `substitute_declined`) zusätzlich zu ausstehenden Zeiteintragskorrekturen; API 401 bei fehlender Anmeldung wo passend; Admin: eigener Abschnitt „Monatsabschluss“; Karenzfeld bleibt editierbar mit Hinweis, dass der Wert gespeichert wird und bei aktivierter Funktion gilt; Wiederöffnen mit durchsuchbarer Mitarbeitenden-Auswahl und klarerer Rollenbeschreibung; Validierungsfehler mit höherem Kontrast über Themes hinweg. Auto-Finalize protokolliert Einzelfehler.
+- **Release-/Signatur-Workflow für Integritätsprüfung gehärtet**: `make release-signed` signiert jetzt den entpackten Release-Archivinhalt (nicht den lokalen Entwicklungs-Checkout), prüft verbotene Entwicklungs-Pfade und packt das signierte Archiv für Deployment/App-Store neu.
+- **Admin-Autorisierung zentral erzwungen**: Zugriffe auf `AdminController`-Routen werden jetzt per Middleware auf App-Admin-Rechte geprüft; nicht berechtigte angemeldete Nutzer erhalten eine konsistente 403-Seite.
+
+### Dokumentation
+
+- **Deployment-Hinweise ergänzt**: Die Release-Dokumentation fordert nun explizit das Deployment aus dem signierten Tarball und beschreibt das typische Fehlerbild (`.git/*` / `node_modules/*`) bei versehentlicher Signierung eines Dev-Trees.
+- **Deployment-Helferskript**: `release/deploy-from-release.sh` hinzugefügt für Deployment aus signierten Release-Archiven mit Sicherheitsprüfungen (verbotene Pfade, erforderliche `signature.json`, optionales Disable/Enable und `occ integrity:check-app`).
+- **Admin-Betrieb**: Nutzer-/Entwicklerdokumentation ergänzt um Einrichtung der App-Admin-Whitelist, Rückfallverhalten bei leerer Auswahl und Verifikation des Role-Gatings im Docker-Testlauf.
+
+## 1.1.12 – 2026-04-09
+
+### Hinzugefügt
+
+- **Revisionssichere Monatsfinalisierung (optional)**: Admin-Schalter `month_closure_enabled` (Standard aus). Mitarbeitende können einen vollen Kalendermonat finalisieren; die App speichert kanonischen JSON-Snapshot, SHA-256-Hashkette, Anhänge-Revisionen, Audit-Ereignisse und ein schlankes PDF. Finalisierte Monate sind über normale App-APIs nicht mehr änderbar; Administrator:innen können einen Monat mit Pflichtbegründung wieder öffnen (Audit). Monatsberichte für finalisierte Monate lesen den gespeicherten Snapshot. Datenbank: `at_month_closure`, `at_month_closure_revision` (Migration `Version1014Date20260409120000`).
+
+### Dokumentation
+
+- Nutzerhandbücher (DE/EN), Entwicklerdokumentation und Compliance-Hinweise zu Monatsabschluss, Aufbewahrung und Grenzen (Nachweis in der App, keine QES) ergänzt.
+
 ## 1.1.11 – 2026-04-09
 
 ### Hinzugefügt

CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Month closure grace period and auto-finalization**: Admin setting `month_closure_grace_days_after_eom` (0–90, default 0). After end-of-month, employees have that many calendar days to finalize manually; if the month is still open afterward, a daily background job finalizes it automatically (same snapshot as manual finalize). Pending time entry approvals and open absence workflow states block auto-finalization. Reopening remains admin-only.
+- **App-admin allowlist**: New admin setting `app_admin_user_ids` to restrict ArbeitszeitCheck administration to a selected subset of Nextcloud admins. Empty selection keeps backward-compatible behavior (all Nextcloud admins can administer the app).
+- **Security role-gating Docker test target**: Added `scripts/test-security-role-gating-docker.sh` wiring via `make test-security-role-gating-docker` and `composer test:security-role-gating:docker` for fast authorization regression checks in containerized setups.
+
+### Changed
+
+- **Month closure UX and API**: Employee UI uses a clearer card layout, visible feedback for success/errors (WCAG-friendly), server-driven `canFinalize` with localized block reasons (feature off, future month, pending approvals). Manual finalize rejects future calendar months. Absence workflow (`pending`, `substitute_pending`, `substitute_declined`) is enforced alongside pending time entry corrections. Unauthorized API access returns 401 where appropriate. Admin settings: dedicated “Month closure” section; grace-days field stays editable with copy explaining it is saved even when closure is off; reopen uses searchable employee picker and clearer administrator vs. employee wording. Form validation error callouts use higher-contrast text and tinted surfaces across themes. Auto-finalize job logs per-user failures for operations.
+- **Release/signing workflow hardened for integrity checks**: `make release-signed` now signs the extracted release archive payload (not the local development checkout), validates forbidden development paths are excluded, and repacks the signed archive for deployment/App Store upload.
+- **Admin authorization enforcement**: Access to `AdminController` routes now uses middleware-level app-admin checks with a dedicated exception and a consistent 403 response page for authenticated users without app-admin rights.
+
+### Documentation
+
+- **Deployment guidance**: Release docs now explicitly require production deployment from the signed tarball only and document the common integrity-failure pattern (`.git/*` / `node_modules/*` lists) caused by signing a dev tree.
+- **Deployment helper script**: Added `release/deploy-from-release.sh` to deploy from signed release archives with safety checks (forbidden path scan, required `signature.json`, optional app disable/enable and `occ integrity:check-app`).
+- **Admin operations**: User/developer docs now describe how to configure app-admin allowlisting, what the default fallback is, and how to verify authorization gating in Docker-based test runs.
+
+## 1.1.12 - 2026-04-09
+
+### Added
+
+- **Revision-safe month finalization (optional)**: Admin toggle `month_closure_enabled` (default off). Employees can finalize a full calendar month; the app stores a canonical JSON snapshot, SHA-256 hash chain, append-only revision rows, audit events, and a minimal PDF download. Finalized months are read-only through normal app APIs; administrators may reopen a month with a mandatory reason (audit). Monthly reports for a finalized month use the stored snapshot. Database: `at_month_closure`, `at_month_closure_revision` (migration `Version1014Date20260409120000`).
+
+### Documentation
+
+- User manuals (EN/DE), developer documentation, and compliance notes updated for month closure, retention context, and limits (in-app tamper evidence, not QES).
+
 ## 1.1.11 - 2026-04-09
 
 ### Added

Makefile

@@ -4,8 +4,11 @@ app_name = arbeitszeitcheck
 build_dir = build
 release_dir = $(build_dir)/release
 version = $(shell grep '^\s*<version>' appinfo/info.xml | sed 's/.*<version>\([0-9.]*\)<\/version>.*/\1/' | head -1)
+archive_name = $(app_name)-$(version).tar.gz
+archive_path = $(release_dir)/$(archive_name)
+occ = ../../occ
 
-.PHONY: release clean
+.PHONY: release verify-release verify-signature-manifest sign-release release-signed clean test-security-role-gating-docker
 
 release:
 	@echo "Building $(app_name) v$(version)..."
@@ -14,10 +17,38 @@ release:
 		mkdir -p "$$staging/$(app_name)" && \
 		rsync -a --exclude='.git' --exclude='$(build_dir)' --exclude='.github' \
 			--exclude='node_modules' --exclude='tests' --exclude='.phpunit.result.cache' \
+			--exclude='scripts' --exclude='release/*.tar.gz' --exclude='release/*.asc' \
+			--exclude='appinfo/signature.json' \
 			./ "$$staging/$(app_name)/" && \
-		tar -czf $(release_dir)/$(app_name).tar.gz -C "$$staging" $(app_name) && \
+		tar -czf $(archive_path) -C "$$staging" $(app_name) && \
 		rm -rf "$$staging"
-	@echo "Created $(release_dir)/$(app_name).tar.gz"
+	@echo "Created $(archive_path)"
+
+verify-release:
+	@test -f $(archive_path) || (echo "Error: Run 'make release' first"; exit 1)
+	@if tar -tzf $(archive_path) | grep -Eq '/(\.git/|node_modules/|build/|tests/|scripts/)'; then \
+		echo "Error: release archive contains forbidden development paths"; \
+		tar -tzf $(archive_path) | grep -E '/(\.git/|node_modules/|build/|tests/|scripts/)' || true; \
+		exit 1; \
+	fi
+	@echo "Release archive layout looks clean."
+
+verify-signature-manifest:
+	@test -f $(archive_path) || (echo "Error: Run 'make release-signed' first"; exit 1)
+	@tmpdir=$$(mktemp -d) && \
+		trap 'rm -rf "$$tmpdir"' EXIT && \
+		tar -xzf $(archive_path) -C "$$tmpdir" "$(app_name)/appinfo/signature.json" && \
+		sig="$$tmpdir/$(app_name)/appinfo/signature.json" && \
+		if ! test -f "$$sig"; then \
+			echo "Error: signature.json missing from signed archive"; \
+			exit 1; \
+		fi && \
+		if grep -Eq '"([^"]*/)?(\.git|node_modules|build|tests|scripts)\\/' "$$sig"; then \
+			echo "Error: signature.json references forbidden development paths"; \
+			grep -E '"([^"]*/)?(\.git|node_modules|build|tests|scripts)\\/' "$$sig" || true; \
+			exit 1; \
+		fi
+	@echo "Signature manifest sanity check passed."
 
 clean:
 	rm -rf $(build_dir)
@@ -26,17 +57,29 @@ clean:
 # Paste the output into the App Store upload form's "Signature" field
 sign-tarball:
 	@test -f ~/.nextcloud/certificates/$(app_name).key || (echo "Error: Missing ~/.nextcloud/certificates/$(app_name).key"; exit 1)
-	@test -f $(release_dir)/$(app_name).tar.gz || (echo "Error: Run 'make release' first"; exit 1)
-	@openssl dgst -sha512 -sign $$HOME/.nextcloud/certificates/$(app_name).key $(release_dir)/$(app_name).tar.gz 2>/dev/null | base64 | tr -d '\n'; echo
+	@test -f $(archive_path) || (echo "Error: Run 'make release' first"; exit 1)
+	@openssl dgst -sha512 -sign $$HOME/.nextcloud/certificates/$(app_name).key $(archive_path) 2>/dev/null | base64 | tr -d '\n'; echo
 
-# Sign the app for Nextcloud App Store (requires certificate)
+# Sign the release archive payload with Nextcloud app signature
+# This signs the extracted archive tree (not your local dev checkout), then repacks it.
 # Generate cert: openssl req -nodes -newkey rsa:4096 -keyout ~/.nextcloud/certificates/arbeitszeitcheck.key -out ~/.nextcloud/certificates/arbeitszeitcheck.csr -subj "/CN=arbeitszeitcheck"
 # Store signed cert as ~/.nextcloud/certificates/arbeitszeitcheck.crt
-sign:
-	@test -f ~/.nextcloud/certificates/$(app_name).key || (echo "Error: Run 'make release' first, then obtain certificate from https://github.com/nextcloud/app-certificate-requests"; exit 1)
+sign-release: verify-release
+	@test -f ~/.nextcloud/certificates/$(app_name).key || (echo "Error: Missing ~/.nextcloud/certificates/$(app_name).key (see https://github.com/nextcloud/app-certificate-requests)"; exit 1)
 	@test -f ~/.nextcloud/certificates/$(app_name).crt || (echo "Error: Store signed certificate at ~/.nextcloud/certificates/$(app_name).crt"; exit 1)
-	php ../../occ integrity:sign-app \
-		--privateKey=$$HOME/.nextcloud/certificates/$(app_name).key \
-		--certificate=$$HOME/.nextcloud/certificates/$(app_name).crt \
-		--path=$$(pwd)
-	@echo "App signed. Commit appinfo/signature.json before release."
+	@test -f $(occ) || (echo "Error: occ not found at $(occ). Override with 'make sign-release occ=/path/to/occ'"; exit 1)
+	@staging=$$(mktemp -d) && \
+		trap 'rm -rf "$$staging"' EXIT && \
+		tar -xzf $(archive_path) -C "$$staging" && \
+		php $(occ) integrity:sign-app \
+			--privateKey=$$HOME/.nextcloud/certificates/$(app_name).key \
+			--certificate=$$HOME/.nextcloud/certificates/$(app_name).crt \
+			--path="$$staging/$(app_name)" && \
+		tar -czf $(archive_path) -C "$$staging" $(app_name)
+	@echo "Signed archive updated at $(archive_path)"
+
+release-signed: release sign-release verify-signature-manifest
+	@echo "Release build + Nextcloud signature complete."
+
+test-security-role-gating-docker:
+	@bash scripts/test-security-role-gating-docker.sh

composer.json

@@ -21,6 +21,8 @@
 	},
 	"scripts": {
 		"test": "phpunit",
+		"test:docker": "bash ../../docker/run-app-phpunit.sh arbeitszeitcheck",
+		"test:security-role-gating:docker": "bash scripts/test-security-role-gating-docker.sh",
 		"test:unit": "phpunit --testsuite unit",
 		"test:integration": "phpunit --testsuite integration",
 		"test:coverage": "phpunit --coverage-html tests/coverage",