diff --git a/Codex-Project-Index.md b/Codex-Project-Index.md index 369fbad..076c06f 100644 --- a/Codex-Project-Index.md +++ b/Codex-Project-Index.md @@ -7,17 +7,22 @@ This page is generated from repository and product-directory project files. - [Product govoplan-split-concept-action-plan](Product govoplan-split-concept-action-plan) - `/mnt/DATA/Nextcloud/ADD ideas UG/Products/govoplan/split-concept-action-plan.md` - [Repo-README](Repo-README) - `/mnt/DATA/git/govoplan-core/README.md` - [Repo-docs-ACCESS-RBAC-MODEL](Repo-docs-ACCESS-RBAC-MODEL) - `/mnt/DATA/git/govoplan-core/docs/ACCESS_RBAC_MODEL.md` +- [Repo-docs-ACTION-EFFECT-AUTOMATION-LAYER](Repo-docs-ACTION-EFFECT-AUTOMATION-LAYER) - `/mnt/DATA/git/govoplan-core/docs/ACTION_EFFECT_AUTOMATION_LAYER.md` - [Repo-docs-CODEX-WORKFLOW](Repo-docs-CODEX-WORKFLOW) - `/mnt/DATA/git/govoplan-core/docs/CODEX_WORKFLOW.md` - [Repo-docs-CONFIGURATION-PACKAGES](Repo-docs-CONFIGURATION-PACKAGES) - `/mnt/DATA/git/govoplan-core/docs/CONFIGURATION_PACKAGES.md` +- [Repo-docs-DEPENDENCY-AUDITS](Repo-docs-DEPENDENCY-AUDITS) - `/mnt/DATA/git/govoplan-core/docs/DEPENDENCY_AUDITS.md` - [Repo-docs-DEPLOYMENT-OPERATOR-GUIDE](Repo-docs-DEPLOYMENT-OPERATOR-GUIDE) - `/mnt/DATA/git/govoplan-core/docs/DEPLOYMENT_OPERATOR_GUIDE.md` - [Repo-docs-DOCUMENTATION-MAP](Repo-docs-DOCUMENTATION-MAP) - `/mnt/DATA/git/govoplan-core/docs/DOCUMENTATION_MAP.md` - [Repo-docs-EVENTS-AND-AUDIT](Repo-docs-EVENTS-AND-AUDIT) - `/mnt/DATA/git/govoplan-core/docs/EVENTS_AND_AUDIT.md` - [Repo-docs-GITEA-ISSUES](Repo-docs-GITEA-ISSUES) - `/mnt/DATA/git/govoplan-core/docs/GITEA_ISSUES.md` - [Repo-docs-GOVERNANCE-MODEL](Repo-docs-GOVERNANCE-MODEL) - `/mnt/DATA/git/govoplan-core/docs/GOVERNANCE_MODEL.md` - [Repo-docs-GOVOPLAN-MASTER-ROADMAP](Repo-docs-GOVOPLAN-MASTER-ROADMAP) - `/mnt/DATA/git/govoplan-core/docs/GOVOPLAN_MASTER_ROADMAP.md` +- [Repo-docs-INTERFACE-ETHICS-AND-DESIGN-DOCTRINE](Repo-docs-INTERFACE-ETHICS-AND-DESIGN-DOCTRINE) - `/mnt/DATA/git/govoplan-core/docs/INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md` - [Repo-docs-MODULE-ARCHITECTURE](Repo-docs-MODULE-ARCHITECTURE) - `/mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md` - [Repo-docs-POLICY-CONTRACTS](Repo-docs-POLICY-CONTRACTS) - `/mnt/DATA/git/govoplan-core/docs/POLICY_CONTRACTS.md` +- [Repo-docs-POSTBOX-E2EE-ARCHITECTURE](Repo-docs-POSTBOX-E2EE-ARCHITECTURE) - `/mnt/DATA/git/govoplan-core/docs/POSTBOX_E2EE_ARCHITECTURE.md` - [Repo-docs-PUBLIC-SECTOR-INTEGRATION-STRATEGY](Repo-docs-PUBLIC-SECTOR-INTEGRATION-STRATEGY) - `/mnt/DATA/git/govoplan-core/docs/PUBLIC_SECTOR_INTEGRATION_STRATEGY.md` - [Repo-docs-RELEASE-DEPENDENCIES](Repo-docs-RELEASE-DEPENDENCIES) - `/mnt/DATA/git/govoplan-core/docs/RELEASE_DEPENDENCIES.md` - [Repo-docs-REMOTE-WEBUI-BUNDLES](Repo-docs-REMOTE-WEBUI-BUNDLES) - `/mnt/DATA/git/govoplan-core/docs/REMOTE_WEBUI_BUNDLES.md` - [Repo-docs-UI-UX-DECISION-LEDGER](Repo-docs-UI-UX-DECISION-LEDGER) - `/mnt/DATA/git/govoplan-core/docs/UI_UX_DECISION_LEDGER.md` +- [Repo-docs-audits-2026-07-09-dependency-audit](Repo-docs-audits-2026-07-09-dependency-audit) - `/mnt/DATA/git/govoplan-core/docs/audits/2026-07-09-dependency-audit.md` diff --git a/Repo-README.md b/Repo-README.md index 89f8e23..468703d 100644 --- a/Repo-README.md +++ b/Repo-README.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/README.md`. > Origin: `repository`. @@ -7,7 +7,7 @@ --- # govoplan-core -GovOPlaN core is the platform runner and shared foundation. It owns the server entry point, database/session primitives, tenant and RBAC infrastructure, governance policy, audit/auth helpers, module discovery, migration registration, and the shared WebUI shell. Feature code is supplied by installed modules. +GovOPlaN core is the platform runner and shared foundation. It owns the server entry point, database/session primitives, module discovery, migration orchestration, capability contracts, install/uninstall orchestration, and the shared WebUI shell. Platform and feature behavior is supplied by installed modules. ## Repository ownership @@ -16,11 +16,14 @@ Core owns: - `govoplan_core.server.app:app`, the FastAPI entry point used by uvicorn - `GovoplanServerConfig`, module discovery, registry validation, and route aggregation - SQLAlchemy base/session helpers and module migration registration -- tenant/account/session/RBAC/governance/audit models and services -- core API routes for auth, admin, platform metadata, audit, and system health +- kernel APIs for platform metadata, module lifecycle, health, and development diagnostics - `@govoplan/core-webui`, including login, CSRF/API helpers, shell layout, generic UI components, IconRail, DataGrid, access boundaries, and module route/nav contracts -Feature modules own their backend routers, models, migrations, permissions, frontend packages, nav items, and route contributions. Core should not import feature pages directly; it imports module manifests and renders their route contributions. +Platform and feature modules own their backend routers, models, migrations, +permissions, frontend packages, nav items, and route contributions. Access, +tenancy, policy, audit, and admin behavior live in their owning platform +modules. Core should not import feature pages directly; it imports module +manifests and renders their route contributions. ## Governance docs @@ -33,7 +36,8 @@ Canonical policy documents live in `docs/`: - [DEPLOYMENT_OPERATOR_GUIDE.md](docs/DEPLOYMENT_OPERATOR_GUIDE.md) - [CODEX_WORKFLOW.md](docs/CODEX_WORKFLOW.md) -Modules may define module-specific permissions and policy behavior, but the platform-level permission model and governance hierarchy belong here. +Modules define module-specific permissions and policy behavior. Shared DTOs and +composition rules live in core only where they are stable kernel contracts. ## Backend development diff --git a/Repo-docs-ACTION-EFFECT-AUTOMATION-LAYER.md b/Repo-docs-ACTION-EFFECT-AUTOMATION-LAYER.md new file mode 100644 index 0000000..5705d58 --- /dev/null +++ b/Repo-docs-ACTION-EFFECT-AUTOMATION-LAYER.md @@ -0,0 +1,128 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-core/docs/ACTION_EFFECT_AUTOMATION_LAYER.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# Action, Effect, And Automation Layer + +GovOPlaN needs an automation layer because administrative processes will not be +only linear screen flows. Workflows, schedules, imports, connectors, policies, +and external events all need to request governed actions without bypassing the +same safety rules that apply to human users. + +The first implementation should live in `govoplan-workflow` and core contracts. +Create a separate `govoplan-automation` module only if action planning, +schedulers, rule execution, or cross-module automation become too broad for +workflow ownership. + +## Layer Purpose + +The automation layer should provide: + +- a typed action catalogue +- a typed effect catalogue +- consequence preview before execution +- policy and permission checks +- idempotent execution +- audit and provenance records +- retry, quarantine, and manual exception handling +- system-actor execution without hiding responsibility + +Automation is not a shortcut around module boundaries. It is a governed caller +of module capabilities. + +## Action Definition + +An `ActionDefinition` describes something a human or system actor can request. + +Recommended fields: + +- `action_key` +- owning module +- input schema +- actor requirements and required scopes +- required capabilities +- policy checks +- risk level +- reversibility class: reversible, compensatable, corrective-only, or + irreversible +- expected effects +- idempotency key strategy +- audit event names +- preview provider + +Examples: + +- create a case from a form submission +- assign a task +- generate a document from a template +- send a postbox message +- send an email notification +- append evidence to records +- create a payment request +- call an external connector + +## Effect Definition + +An `EffectDefinition` describes the expected and observed result of an action. + +Recommended fields: + +- `effect_key` +- affected module and resource references +- external system references where applicable +- created, changed, deleted, sent, notified, locked, or retained markers +- visibility and privacy classification +- audit event references +- rollback or compensation hints +- operator-facing explanation + +Effects should be recorded even when execution fails partially. This makes +manual recovery and audit review possible. + +## Execution Model + +The runner should execute an action plan as follows: + +1. Resolve actor context: human, delegated actor, or system actor. +2. Validate input schema. +3. Resolve required module capabilities. +4. Run permission and policy checks. +5. Generate a consequence preview. +6. Reserve or verify the idempotency key. +7. Execute the owning module capability. +8. Record observed effects. +9. Emit events and audit records. +10. Mark the command complete, retryable, quarantined, or requiring manual + intervention. + +The runner must never advance workflow state past a required side effect unless +the action definition explicitly allows asynchronous completion and the pending +state is visible. + +## Failure States + +Automation should use explicit failure states: + +- `blocked`: policy, permission, missing capability, or invalid input prevents + execution. +- `retryable`: transient transport, timeout, rate-limit, or lock conflict. +- `quarantined`: unexpected response, schema mismatch, unsafe partial result, + or unknown external state. +- `manual_required`: human decision or correction is needed. +- `compensation_required`: a later action must correct an already observed + side effect. + +These states should be visible in workflow, task, and admin diagnostics. + +## Boundary + +Core may own stable DTOs, registry contracts, and generic audit/event hooks. +`govoplan-workflow` should own the first runner because workflow is the first +module that coordinates cross-module process actions. + +Domain modules own their own action providers. For example, templates own +document generation actions, postbox owns postbox message actions, and +connectors own external handoff actions. diff --git a/Repo-docs-DEPENDENCY-AUDITS.md b/Repo-docs-DEPENDENCY-AUDITS.md new file mode 100644 index 0000000..a879bd9 --- /dev/null +++ b/Repo-docs-DEPENDENCY-AUDITS.md @@ -0,0 +1,74 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-core/docs/DEPENDENCY_AUDITS.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# Dependency Audits + +GovOPlaN keeps dependency vulnerability checks reproducible but separate from +the fast local smoke suite, because both Python and npm audits need network +metadata and can fail for newly disclosed advisories without a source change. + +## Local Workflow + +Install the development audit dependency once: + +```bash +cd /mnt/DATA/git/govoplan-core +./.venv/bin/python -m pip install -r requirements-dev.txt +``` + +Run both backend and WebUI production audits: + +```bash +cd /mnt/DATA/git/govoplan-core +bash scripts/check-dependency-audits.sh +``` + +The script runs: + +- `scripts/check-dependency-hygiene.sh` for pip resolver consistency, stale + legacy editable package metadata, deprecated framework constants, and the + Starlette `TestClient` deprecation smoke when test dependencies are present +- `python -m pip_audit --progress-spinner off` +- `npm audit --omit=dev` in `webui` + +For fast local checks without vulnerability metadata lookups, run: + +```bash +cd /mnt/DATA/git/govoplan-core +CHECK_TESTCLIENT_DEPRECATIONS=1 bash scripts/check-dependency-hygiene.sh +``` + +This is also part of `scripts/check-focused.sh`, so resolver drift and +deprecation regressions fail close to the code change that introduced them. + +Override tool paths when testing from a disposable environment: + +```bash +PYTHON=/tmp/govoplan-audit/bin/python \ +NPM=/home/zemion/.nvm/versions/node/v22.22.3/bin/npm \ +bash scripts/check-dependency-audits.sh +``` + +## CI Workflow + +`.gitea/workflows/dependency-audit.yml` installs release dependencies from +tagged package refs, installs `pip-audit`, and runs the same script on pushes, +pull requests, and a weekly schedule. + +The workflow intentionally uses release dependency refs instead of local +`file:` or editable sibling paths. Development lockfiles may keep local module +links, but release audit results should represent the installable product. + +## Recording Results + +When closing or triaging dependency-audit issues, add a short dated note under +`docs/audits/`. Record: + +- the commands that were run +- whether Python and npm passed +- any advisories accepted as temporary risk +- follow-up issue links for required upgrades diff --git a/Repo-docs-DOCUMENTATION-MAP.md b/Repo-docs-DOCUMENTATION-MAP.md index e6abe98..02365ee 100644 --- a/Repo-docs-DOCUMENTATION-MAP.md +++ b/Repo-docs-DOCUMENTATION-MAP.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/DOCUMENTATION_MAP.md`. > Origin: `repository`. @@ -20,6 +20,8 @@ operator, and roadmap pages. | Governance hierarchy | `GOVERNANCE_MODEL.md` | System, tenant, user/group, campaign policy inheritance and admin UI structure. | | Policy decision DTOs and provenance | `POLICY_CONTRACTS.md` | Shared explain/provenance shape; module-specific policy docs should link here. | | Events and audit trace context | `EVENTS_AND_AUDIT.md` | Event dispatch semantics and audit payload conventions. | +| Action/effect automation layer | `ACTION_EFFECT_AUTOMATION_LAYER.md` | Action/effect contracts, consequence preview, runner semantics, and module boundary for automation. | +| Postbox E2EE target architecture | `POSTBOX_E2EE_ARCHITECTURE.md` | Strategic encrypted postbox/mailbox model, key ownership, role mailbox semantics, and retraction limits. | ## Release And Operations @@ -27,6 +29,7 @@ operator, and roadmap pages. | --- | --- | --- | | Runtime configuration and operator flow | `DEPLOYMENT_OPERATOR_GUIDE.md` | Production/staging configuration, migrations, backups, installer operation, and rollback drill. | | Release dependencies and catalogs | `RELEASE_DEPENDENCIES.md` | Release package refs, migration baselines, release lockfiles, catalog trust/licensing, catalog publishing, and release checklist. | +| Dependency vulnerability audits | `DEPENDENCY_AUDITS.md` | Local and CI audit commands plus dated audit result notes. | | Remote WebUI bundle design | `REMOTE_WEBUI_BUNDLES.md` | Experimental controlled-deployment design; normal releases still use package builds. | ## Product And Module Planning @@ -35,6 +38,7 @@ operator, and roadmap pages. | --- | --- | --- | | Product roadmap and module routing | `GOVOPLAN_MASTER_ROADMAP.md` | Product-level sequencing, implementation gates, issue routing, and missing-module decisions. | | UI/UX decisions | `UI_UX_DECISION_LEDGER.md` | Binding guided-UI decisions, open decisions, impact index, and review checklist. | +| Interface ethics and design doctrine | `INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md` | Product-level doctrine for context, decision, consequence, contestability, responsibility, and traceability. | | Public-sector integration posture | `PUBLIC_SECTOR_INTEGRATION_STRATEGY.md` | Strategy index; executable target inventory lives in `govoplan-connectors`. | | Configuration packages | `CONFIGURATION_PACKAGES.md` | Package model, provider contract, import/export flow, and tracking slices. | diff --git a/Repo-docs-GOVOPLAN-MASTER-ROADMAP.md b/Repo-docs-GOVOPLAN-MASTER-ROADMAP.md index e98ef72..574739e 100644 --- a/Repo-docs-GOVOPLAN-MASTER-ROADMAP.md +++ b/Repo-docs-GOVOPLAN-MASTER-ROADMAP.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/GOVOPLAN_MASTER_ROADMAP.md`. > Origin: `repository`. @@ -32,12 +32,20 @@ The product should first provide a reliable administrative spine: - identities, roles, tenants, policy, audit, and governance - forms, files, cases, workflow, tasks, templates, and records - postboxes, notifications, mail, portal, appointments, and booking +- identity trust, role-bound postboxes, and eventually encrypted administrative + communication - configuration packages that assemble modules into repeatable procedures - docs that explain the configured system, not the full theoretical product Domain modules should come after the spine can run a reference procedure end to end. +The platform should be a governance-capable runtime for modules, connectors, +configuration, and administrative decisions. The kernel must stay free of domain +semantics while still providing the contracts needed for modules to explain what +they do, what they require, which effects they create, and how operators can +verify or reverse those effects. + ## Design Principles - Modules must stay independently installable, enableable, and disableable. @@ -48,6 +56,16 @@ end. - Operators should be able to configure the platform through the UI. - Every powerful configuration path needs preflight, preview, audit, rollback, RBAC, and policy checks. +- Context, decision, consequence, and traceability must be visible together for + consequential actions. The full doctrine lives in + `INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md`. +- Automation must use governed action/effect contracts, not hidden side + effects. The first automation layer is defined in + `ACTION_EFFECT_AUTOMATION_LAYER.md` and should start in `govoplan-workflow` + unless a separate automation module becomes justified. +- Encrypted postboxes are a strategic target. Early postbox, access, and + identity-trust contracts should stay compatible with the E2EE architecture in + `POSTBOX_E2EE_ARCHITECTURE.md`. - Integration should be a first-class product path: connect to existing systems, consume their data, and publish governed outputs back to them. - GovOPlaN should scale from a small local installation to a larger deployment @@ -123,9 +141,12 @@ pattern exists. | Uploaded files and managed storage | `govoplan-files` | | Case record and lifecycle | `govoplan-cases` | | Workflow transitions and automation | `govoplan-workflow` | +| Action/effect catalogue and automation runner | first `govoplan-workflow`; possible future `govoplan-automation` if it outgrows workflow | | Internal work queues and tasks | `govoplan-tasks` | | Appointment proposals and booking | `govoplan-appointments`, `govoplan-calendar` | -| Postbox, email, and notifications | `govoplan-mail`, `govoplan-notifications` | +| Postbox, email, and notifications | `govoplan-postbox`, `govoplan-mail`, `govoplan-notifications` | +| Identity trust, device keys, and encrypted postbox key contracts | `govoplan-identity-trust`, `govoplan-access`, `govoplan-postbox` | +| Service directory/catalog | `govoplan-portal` | | Permit/document generation | `govoplan-templates`, `govoplan-dms` | | Payment capture and accounting handoff | `govoplan-payments`, `govoplan-ledger` | | Roles, permissions, tenants, policy, audit | `govoplan-access`, `govoplan-tenancy`, `govoplan-policy`, `govoplan-audit` | @@ -235,8 +256,10 @@ Refine: - `govoplan-core`: module discovery, capabilities, events, migrations, release catalog, configuration package runtime, WebUI shell. - `govoplan-access`: identities, sessions, API keys, users, groups, roles, - memberships, RBAC decisions. + memberships, function assignments, delegation, RBAC decisions. - `govoplan-tenancy`: tenant and organizational-unit boundaries. +- `govoplan-identity-trust`: initial trust contracts for device keys, public key + directory, assurance, and later encrypted postbox key access. - `govoplan-policy`: policy sources, policy decisions, retention inputs. - `govoplan-audit`: audit sink, audit routes, trace context, retention cooperation. @@ -254,6 +277,10 @@ Exit criteria: - module enablement and capability lookup are stable - configuration package preflight works for at least one simple package - audit and policy decisions are visible in admin flows +- access distinguishes identity, account, function, role, and right in durable + contracts +- action/effect automation contracts are specified before hidden side effects + spread across modules - docs can show installed/enabled modules and configured routes ### Wave 1: Permit-To-Payment MVP @@ -274,7 +301,8 @@ Create or refine in this order: 6. `govoplan-tasks`: work queues, assignments, due dates, and follow-ups. 7. `govoplan-templates`: permit/decision document generation. 8. `govoplan-postbox`, `govoplan-mail`, `govoplan-notifications`: applicant and - internal communication. + internal communication, with the postbox model compatible with later E2EE + and role-bound access. 9. `govoplan-calendar`, `govoplan-appointments`, `govoplan-booking`: appointment or booking handoff for the reference process. 10. `govoplan-payments`, `govoplan-ledger`, `govoplan-xrechnung`: payment @@ -528,7 +556,8 @@ Defer these until a reference journey proves the need: - broad BI/dataflow platform - every possible public-sector protocol adapter - rich LMS behavior beyond training administration -- advanced digital signing and trust features beyond certificate verification +- full qualified digital signing/trust services beyond the identity-trust and + encrypted-postbox contracts needed for early architecture safety - mobile apps - AI assistants embedded into workflows @@ -546,6 +575,12 @@ repositories or to explicit missing-module decisions. | Permit-to-payment configuration package | `govoplan-core` plus participating modules | `add-ideas/govoplan-core#214` | | Fully UI-managed configuration with safety controls | `govoplan-admin`, `govoplan-core`, `govoplan-policy`, `govoplan-access`, `govoplan-audit` | `add-ideas/govoplan-core#218` | | Access as a module | `govoplan-access` | `add-ideas/govoplan-access#7` | +| Interface ethics and decision-consequence doctrine | `govoplan-core` plus all UI-owning modules | `add-ideas/govoplan-core#227` | +| Action/effect automation layer | first `govoplan-workflow`; possible future `govoplan-automation` | `add-ideas/govoplan-workflow#1` | +| E2EE role/function postbox architecture | `govoplan-postbox`, `govoplan-identity-trust`, `govoplan-access`, `govoplan-policy`, `govoplan-audit` | `add-ideas/govoplan-postbox#15`, `add-ideas/govoplan-identity-trust#1` | +| Identity, account, function, role, right semantic model | `govoplan-access` | `add-ideas/govoplan-access#9` | +| Role-based service directory/catalog | `govoplan-portal` | `add-ideas/govoplan-portal#1` | +| Unified inbox across tasks, postbox, notifications, and portal | `govoplan-core` coordination plus owning modules | `add-ideas/govoplan-tasks#1`, `add-ideas/govoplan-notifications#1` | | OpenProject API / project management connector | `govoplan-connectors` | `add-ideas/govoplan-connectors#1` | | Native project-management module decision | connector-first through `govoplan-connectors`; no native project module yet | `add-ideas/govoplan-core#196`, `add-ideas/govoplan-connectors#1` | | Datasources for databases, CSV, files, APIs | no repository yet; start with connectors/files/reporting and create `govoplan-datasources` only after the first package proves shared source-catalog ownership | `add-ideas/govoplan-core#197` | @@ -561,6 +596,7 @@ repositories or to explicit missing-module decisions. | Connectors module concept | `govoplan-connectors` | `add-ideas/govoplan-core#176` | | Adrema-style address and distribution-list management | `govoplan-addresses` | `add-ideas/govoplan-addresses#1` | | Consume sources and become a governed source | `govoplan-connectors` plus possible future `govoplan-dataflow` | `add-ideas/govoplan-connectors#3`, `add-ideas/govoplan-core#198` | +| Governed connector configuration, dry-run, and simulation runtime | `govoplan-connectors` | `add-ideas/govoplan-connectors#6` | | Terminfindung and meeting scheduling polls | `govoplan-scheduling`; calendar primitives remain in calendar | `add-ideas/govoplan-core#193`, `add-ideas/govoplan-scheduling#1` | | Terminplaner and calendar primitives | `govoplan-calendar` | `add-ideas/govoplan-core#193`, `add-ideas/govoplan-calendar#1` | | Terminbuchung appointment booking | `govoplan-appointments` | `add-ideas/govoplan-core#193`, `add-ideas/govoplan-appointments#1` | @@ -589,6 +625,10 @@ Boundary rationale lives in `MODULE_ARCHITECTURE.md`. Current decisions: - OpenProject is connector-first; no native projects module yet - public-sector integration strategy stays in core; executable catalogue work lives in connectors +- encrypted postbox and identity-trust are strategic contracts, not mail-module + behavior +- automation starts as workflow-owned action/effect execution and may split into + a dedicated module only after the runner becomes broader than workflow The following modules are intentionally not created yet: diff --git a/Repo-docs-INTERFACE-ETHICS-AND-DESIGN-DOCTRINE.md b/Repo-docs-INTERFACE-ETHICS-AND-DESIGN-DOCTRINE.md new file mode 100644 index 0000000..8a5340e --- /dev/null +++ b/Repo-docs-INTERFACE-ETHICS-AND-DESIGN-DOCTRINE.md @@ -0,0 +1,109 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-core/docs/INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# GovOPlaN Interface Ethics And Design Doctrine + +This document captures the product-level design doctrine for GovOPlaN. It is +more durable than an individual screen design and should guide admin, +configuration, workflow, policy, portal, and operational UI decisions. + +GovOPlaN is meant to support administrative responsibility. The interface must +therefore make context, decision, consequence, and traceability visible enough +that users can act deliberately instead of being pushed through opaque +automation. + +## Core Doctrine + +1. Context, decision, and consequence belong together. +2. Decisions should not silently happen. +3. Transparency comes before convenience when rights, duties, records, money, + access, or legal effects are involved. +4. Explicit state is preferable to implicit state. +5. Navigation is not consent. +6. Responsibility cannot be delegated to the system. +7. Traceability is part of the action, not a later reporting feature. +8. Context loss is a product defect. + +These rules do not mean every screen should become verbose. They mean the +interface must expose the right explanation at the moment of decision and keep +technical detail available without making it the default surface. + +## Decision Surface Contract + +Any action that changes records, rights, policies, retention, communication, +payments, external systems, or workflow state should answer these questions +before execution: + +- What object, person, organization, or process is affected? +- Which authority or role allows the actor to do this? +- What will change immediately? +- What downstream effects may happen? +- Can the action be undone, superseded, or only corrected later? +- What evidence or audit entry will be created? +- Which policy, configuration, or missing capability blocks the action? +- Who can resolve a blocker? + +The answer may be shown through inline labels, a review step, a side panel, a +problem list, or a confirmation dialog. The important point is that consequence +and responsibility are not hidden behind a generic submit button. + +## Contestability + +Administrative decisions are often contestable or reviewable. GovOPlaN should +therefore preserve the path from input to decision: + +- source data and attachments +- workflow state and task assignment +- policy decisions and source path +- actor and delegation context +- generated document/template version +- external handoff result +- notification or postbox delivery evidence +- retention and record classification state + +Where a user sees a decision, they should be able to reach the provenance that +explains how the system got there. This is especially important for denials, +locks, calculated defaults, generated documents, payment state, retention +state, and access decisions. + +## Anti-Patterns + +Avoid these patterns in GovOPlaN interfaces: + +- Magical buttons that execute multiple side effects without preview. +- Process tunnels that hide where the user is in an administrative procedure. +- Silent automation that changes external systems without an audit-visible + command record. +- Friendly hiding that removes complexity at the cost of obscuring authority, + consequence, or accountability. +- Disabled controls without actionable explanation. +- Configuration screens that ask users to edit raw JSON as the normal path. + +## Automation Rule + +Automation must use the same governed action surface as a human actor. The +system may execute actions as a system actor, but it must still run through +policy checks, capability contracts, audit, idempotency, and failure handling. + +When an automated decision is not clear, GovOPlaN should create a manual +exception, task, or review item instead of guessing silently. + +## Relationship To UI Components + +Shared components should make this doctrine easy to follow: + +- preflight and problem-list components for blockers +- policy source path and effective decision displays +- action review panels for consequence preview +- audit/provenance links on decision outputs +- guided dialogs for risky configuration +- disabled-action explanations with actor and next step +- confirmation dialogs that distinguish reversible, corrective, and destructive + actions + +The UI/UX decision ledger defines concrete implementation rules. This doctrine +defines why those rules exist. diff --git a/Repo-docs-MODULE-ARCHITECTURE.md b/Repo-docs-MODULE-ARCHITECTURE.md index 33798fe..814dcae 100644 --- a/Repo-docs-MODULE-ARCHITECTURE.md +++ b/Repo-docs-MODULE-ARCHITECTURE.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md`. > Origin: `repository`. @@ -139,15 +139,16 @@ published from `govoplan_access.auth`. Routers may import that public API for Current live table ownership: -- `govoplan-tenancy`: `tenants` -- `govoplan-access`: `accounts`, `users`, `groups`, `roles`, - `system_role_assignments`, `user_group_memberships`, - `user_role_assignments`, `group_role_assignments`, `api_keys`, - `auth_sessions` -- `govoplan-admin`: `governance_templates`, - `governance_template_assignments` +- `govoplan-tenancy`: `tenancy_tenants` +- `govoplan-access`: `access_accounts`, `access_users`, `access_groups`, + `access_roles`, `access_system_role_assignments`, + `access_user_group_memberships`, `access_user_role_assignments`, + `access_group_role_assignments`, `access_api_keys`, + `access_auth_sessions` +- `govoplan-admin`: `admin_governance_templates`, + `admin_governance_template_assignments` - `govoplan-audit`: `audit_log` -- `govoplan-core`: `system_settings` +- `govoplan-core`: `core_system_settings` Current admin route ownership follows the same boundary: access contributes users, groups, roles, system accounts/roles, auth, sessions, and API-key @@ -982,6 +983,13 @@ cd /mnt/DATA/git/govoplan-core ./.venv/bin/python scripts/check_dependency_boundaries.py ``` +Focused module contract and permutation verification: + +```bash +cd /mnt/DATA/git/govoplan-core +bash scripts/check-module-matrix.sh +``` + Core WebUI host verification: ```bash diff --git a/Repo-docs-POSTBOX-E2EE-ARCHITECTURE.md b/Repo-docs-POSTBOX-E2EE-ARCHITECTURE.md new file mode 100644 index 0000000..1d3be98 --- /dev/null +++ b/Repo-docs-POSTBOX-E2EE-ARCHITECTURE.md @@ -0,0 +1,141 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-core/docs/POSTBOX_E2EE_ARCHITECTURE.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# Postbox End-To-End Encryption Architecture + +This document records the strategic encryption target for GovOPlaN postboxes. +It does not require the first postbox implementation to ship full E2EE, but it +defines the architecture so early data models and APIs do not make the stronger +model impossible. + +The core principle is that a postbox can become a trusted administrative +communication channel without requiring the server to see plaintext content. +The server may route, store, authorize, audit, retain, and expire messages while +message bodies and attachments remain client-encrypted. + +## Goals + +- asynchronous encrypted delivery for internal and portal-facing postboxes +- personal, organizational, role-bound, and function-bound postboxes +- attachments encrypted with the message +- access based on current role/function membership when configured +- honest retraction and expiry semantics +- auditable key access, delivery, and fetch events +- support for external recipients without platform accounts +- replaceable identity and trust providers + +## Envelope Model + +The target model is envelope encryption: + +- Generate one random data encryption key per message or attachment set. +- Encrypt content with an authenticated encryption algorithm. +- Wrap the data encryption key for each authorized recipient or role mailbox. +- Store only ciphertext, wrapped keys, signed manifests, and governed metadata + on the server. + +Algorithm choices should remain replaceable behind a crypto profile. The first +profile should prefer standard, reviewed primitives such as HPKE for key +wrapping and AEAD encryption for content. + +## Identity And Device Keys + +The platform should distinguish: + +- account identity +- tenant membership +- role/function assignment +- device key +- postbox binding + +Identity providers and directories can authenticate users and provide membership +facts, but they must not see postbox private keys or message plaintext. + +The trust layer should provide: + +- public key directory +- account or identity signing keys +- per-device encryption keys +- device registration and revocation +- key rotation and epoch tracking +- recovery policy hooks + +## Role And Function Postboxes + +Role-bound access needs special handling. A postbox can be bound to an +organizational unit and a role or function. Current members can access current +messages according to policy; former members should lose access to not-yet +fetched material when revocation is still technically enforceable. + +The target design should support role encryption keys or an equivalent +rewrapping service: + +- sender encrypts the content key for the role/function postbox +- access service verifies current membership and required assurance +- trust service rewraps the content key to the actor's current device key +- audit records the key access decision and fetch event + +Key epochs are required when role membership changes. Older messages may remain +readable according to policy, but new access must use the current epoch. + +## External Recipients + +External recipients may need one-time or time-limited access without a full +platform account. The target model should support capability links or invitation +tokens that are: + +- scoped to specific message or attachment resources +- time-limited +- optionally one-time +- protected by an out-of-band secret, passphrase, or stronger external identity + proof +- revocable before key fetch +- fully audited + +## Retraction Semantics + +GovOPlaN should be honest about retraction. + +Before a recipient fetches a key or decrypts content, the system can revoke +tokens, remove wrapped-key access, expire links, and delete ciphertext according +to retention policy. + +After a recipient has decrypted or copied plaintext, the system cannot make the +recipient forget it. The platform can only record access, revoke future access, +notify parties, and apply legal or organizational controls. + +The UI must explain this distinction whenever it offers expiry, retraction, or +message withdrawal. + +## Server Responsibilities + +The server remains important even when content is encrypted: + +- store ciphertext and signed manifests +- store routing and policy metadata +- enforce access before key release or rewrapping +- provide public key directory access +- emit notifications without plaintext content +- record audit events +- enforce retention and expiry where possible +- expose diagnostics for delivery and key-access failures + +## Module Ownership + +- `govoplan-postbox` owns postbox bindings, postbox messages, message metadata, + and postbox UI. +- `govoplan-identity-trust` owns device keys, public key directory, key epochs, + and assurance integration. +- `govoplan-access` owns current identity, membership, function, delegation, and + permission decisions. +- `govoplan-policy` owns retention, retraction, and security policy decisions. +- `govoplan-audit` owns durable audit traces. +- `govoplan-files` owns managed file storage when encrypted postbox attachments + are backed by file objects. + +No module should import another module's internals to decrypt content. All +interaction must use capabilities, DTOs, and audited service contracts. diff --git a/Repo-docs-RELEASE-DEPENDENCIES.md b/Repo-docs-RELEASE-DEPENDENCIES.md index 929acb6..c0a3aa8 100644 --- a/Repo-docs-RELEASE-DEPENDENCIES.md +++ b/Repo-docs-RELEASE-DEPENDENCIES.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/RELEASE_DEPENDENCIES.md`. > Origin: `repository`. @@ -226,6 +226,20 @@ through deployment configuration. Fetching trusted keys from the same public origin as the catalog is convenient, but that origin must not become the only trust root. +## Dependency Audits + +Dependency vulnerability checks are documented in +[`DEPENDENCY_AUDITS.md`](DEPENDENCY_AUDITS.md). The local audit runner is: + +```bash +cd /mnt/DATA/git/govoplan-core +bash scripts/check-dependency-audits.sh +``` + +The Gitea workflow in `.gitea/workflows/dependency-audit.yml` runs the same +check against release dependency refs on pushes, pull requests, and a weekly +schedule. + Keyring entries support: - `key_id` diff --git a/Repo-docs-UI-UX-DECISION-LEDGER.md b/Repo-docs-UI-UX-DECISION-LEDGER.md index 65bd402..3ccf307 100644 --- a/Repo-docs-UI-UX-DECISION-LEDGER.md +++ b/Repo-docs-UI-UX-DECISION-LEDGER.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/UI_UX_DECISION_LEDGER.md`. > Origin: `repository`. @@ -22,6 +22,11 @@ with every option at once. Non-technical users should be able to complete common workflows through guided, plain-language flows. Expert and diagnostic detail may exist, but it must be deliberately layered. +The ethical design doctrine in `INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md` is the +normative baseline for this ledger. A screen can be visually quiet and still be +ethically complete only when it preserves context, consequence, +contestability, responsibility, and traceability at the point of action. + ## Binding Decisions | ID | Decision | Status | Applies To | @@ -35,6 +40,11 @@ exist, but it must be deliberately layered. | UX-007 | Creation/editing should prefer modals or focused step flows when it reduces page clutter. Overview and comparison screens remain full-page. | Accepted | Settings/admin surfaces | | UX-008 | Similar concepts must use shared placement and components: server/credential/policy rows, problem lists, review steps, advanced panels, confirmation modals, and empty/error states. | Accepted | Core WebUI and module WebUIs | | UX-009 | Preflight and diagnostics are product UX. Validation, policy, permission, dependency, and capability failures must be written for operators before exposing internal details. | Accepted | Installer, connectors, policy, package import | +| UX-010 | Context, decision, and consequence must be visible together for actions that affect rights, duties, records, money, communication, retention, external systems, or workflow state. | Accepted | Workflow, admin, portal, policy, connector, records, payments | +| UX-011 | Navigation is not consent. Route changes, panel switches, and passive selection must not execute consequential actions without an explicit action surface. | Accepted | All WebUI surfaces | +| UX-012 | Automated actions must remain inspectable. The UI must show the system actor, trigger, policy result, observed effects, and failure/manual-intervention state when automation changes administrative state. | Accepted | Workflow, automation, connectors, tasks, audit | +| UX-013 | Contestable decisions must expose provenance. Denials, locks, generated outputs, calculated defaults, policy decisions, access decisions, and retention decisions need a reachable source path. | Accepted | Policy, access, templates, workflow, retention, records | +| UX-014 | Retraction, expiry, undo, rollback, and delete controls must state the real limit of the operation. Corrective or future-only actions must not be described as if they undo already observed effects. | Accepted | Postbox, files, records, installer, workflow, payments | ## Confirmed Implementation Decisions @@ -167,6 +177,8 @@ converted or reviewed. | Module install/uninstall | Operationally risky, currently inherently technical. | Operator wizard with preflight, maintenance, daemon handoff, review, and rollback explanation. | | Configuration packages | Could become package JSON editing. | Package catalog/import wizard using provider data requirements and problem lists. | | Retention/privacy | High-risk settings need explanation and provenance. | Layered editor with plain-language consequences and review. | +| Automation/workflow commands | Hidden side effects would undermine accountability. | Action/effect preview, system-actor display, command record, retry/quarantine/manual states, and audit links. | +| Postbox and encrypted communication | Retraction and access can be misunderstood. | Honest key-fetch/decryption state, expiry limits, recipient/device access provenance, and delivery evidence. | | API keys | Security-sensitive creation and scope selection. | Scoped creation wizard, least-privilege suggestions, clear expiry/owner explanation. | | User settings | Needs clarity and persistence across profile/interface/preferences. | Simple settings sections with immediate feedback and no double-click navigation traps. | @@ -185,6 +197,11 @@ Every new or changed admin/configuration surface should answer: help, and review? - Is there a review or preflight step before broad, destructive, or risky changes? +- Does the action surface show consequence, reversibility, and audit evidence + when rights, duties, records, money, communication, external systems, or + workflow state are affected? +- If automation is involved, can the user see the trigger, system actor, + observed effects, and failure/manual-intervention state? - Are technical details available without being the first thing the user sees? ## Revision Rule diff --git a/Repo-docs-audits-2026-07-09-dependency-audit.md b/Repo-docs-audits-2026-07-09-dependency-audit.md new file mode 100644 index 0000000..916109e --- /dev/null +++ b/Repo-docs-audits-2026-07-09-dependency-audit.md @@ -0,0 +1,78 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-core/docs/audits/2026-07-09-dependency-audit.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# Dependency Audit - 2026-07-09 + +Commands: + +```bash +cd /mnt/DATA/git/govoplan-core +bash scripts/check-dependency-audits.sh +``` + +Status: remediated. + +Initial result: + +- Python audit failed: 24 advisories were reported across `cryptography`, + `pip`, `python-multipart`, `pyzipper`, and `starlette`. +- npm production audit passed: `npm audit --omit=dev` reported 0 + vulnerabilities. + +Python findings: + +| Package | Installed | Advisory count | Minimum reported fix | +| --- | ---: | ---: | --- | +| `cryptography` | `44.0.0` | 5 | `48.0.1` | +| `pip` | `26.0.1` | 3 | `26.1.2` | +| `python-multipart` | `0.0.17` | 7 | `0.0.31` | +| `pyzipper` | `0.3.6` | 1 | `0.4.0` | +| `starlette` | `0.41.3` | 8 | `1.3.1` | + +Private GovOPlaN packages were skipped by `pip-audit` because they are not +published on PyPI. That is expected for local editable development installs. + +The remediation below upgrades those dependencies and records the compatibility +checks run against core, files, and campaign behavior. + +## Remediation + +Remediation applied on 2026-07-09: + +- upgraded core's FastAPI floor to `fastapi>=0.139,<1`, resolving Starlette to + `starlette==1.3.1` +- upgraded core's cryptography floor to `cryptography>=48.0.1,<50`, resolving + to `cryptography==49.0.0` +- declared the files module upload parser dependency as + `python-multipart>=0.0.31,<1`, resolving to `python-multipart==0.0.32` +- upgraded the campaign ZIP dependency to `pyzipper>=0.4,<1`, resolving to + `pyzipper==0.4.0` +- upgraded the local audit environment to `pip==26.1.2` +- removed the obsolete local `govoplan-module-multimailer` editable install + from the audit environment so the audit reflects the split module product + +Post-remediation result: + +- `bash scripts/check-dependency-audits.sh`: passed, no known Python + vulnerabilities found and npm production audit reported 0 vulnerabilities. +- `python -m pip check`: passed. +- `bash scripts/check-module-matrix.sh`: passed. +- `python -m unittest tests.test_api_smoke`: passed. +- campaign encrypted/plain ZIP smoke with `pyzipper==0.4.0`: passed. + +Notes: + +- `pip-audit` still reports private GovOPlaN packages as skipped because they + are not published on PyPI. That is expected for editable local development + installs. +- `httpx2>=2.5,<3` is included in development requirements so Starlette's + `TestClient` uses the non-deprecated backend. `httpx==0.28.1` remains in dev + requirements for tests that mock connector HTTP responses directly. +- Split-module API routers now use Starlette's renamed + `HTTP_422_UNPROCESSABLE_CONTENT` status constant. This preserves the 422 + status code while avoiding the deprecated `HTTP_422_UNPROCESSABLE_ENTITY` + alias.