From 3d35e9ae608e76c7f787cec7c59e36344ef0c507 Mon Sep 17 00:00:00 2001 From: zwitschi Date: Mon, 10 Nov 2025 08:25:38 +0100 Subject: [PATCH] Enhance security documentation with details on administrative credentials, credential reset process, route guard dependencies, and session management. --- architecture/08_concepts/03_security.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/architecture/08_concepts/03_security.md b/architecture/08_concepts/03_security.md index 53159d6..1e0256d 100644 --- a/architecture/08_concepts/03_security.md +++ b/architecture/08_concepts/03_security.md @@ -12,6 +12,20 @@ Role-based access controls (RBAC) are implemented to restrict data access based Also see [Authentication and Authorization](../08_concepts.md#authentication-and-authorization) and the [Data Model](../08_concepts/02_data_model.md#user-roles) sections. +- Default administrative credentials are provided at deployment time through environment variables (`CALMINER_SEED_ADMIN_EMAIL`, `CALMINER_SEED_ADMIN_USERNAME`, `CALMINER_SEED_ADMIN_PASSWORD`, `CALMINER_SEED_ADMIN_ROLES`). These values are consumed by a shared bootstrap helper on application startup, ensuring mandatory roles and the administrator account exist before any user interaction. +- Operators can request a managed credential reset by setting `CALMINER_SEED_FORCE=true`. On the next startup the helper rotates the admin password and reapplies role assignments, so downstream environments must update stored secrets immediately after the reset. +- The bootstrap helper is idempotent; when no changes are required, startup completes without mutating the database, preserving audit trails while still verifying the presence of required roles. + +### Route Guard Dependencies + +- `require_project_resource` and `require_scenario_resource` build on service-level authorization helpers to enforce role checks while resolving requested entities. +- `require_project_scenario_resource` ensures the scenario referenced by a request belongs to the provided project identifier before continuing processing. +- These dependencies surface 401/403/404 responses consistently across API and UI handlers and can be composed with additional ownership checks when project member metadata is introduced. + +## Session Management + +Authentication relies on a pair of signing tokens issued as `calminer_access_token` and `calminer_refresh_token` HttpOnly cookies. An `AuthSessionMiddleware` component validates incoming access tokens, refreshes them when still covered by a valid refresh token, and attaches the resolved user context to `request.state.auth_session`. Logout clears both cookies and redirects users back to the login form. This approach keeps credentials out of JavaScript, supports transparent rotation of short-lived access tokens, and ensures templates can adapt their navigation to the current session state. + ## Audit Logging Comprehensive logging of user activities and system events is maintained for monitoring and auditing purposes. Also see [Error Handling and Logging](../08_concepts.md#error-handling-and-logging) section for more details.