From da735b38dbb4a0e18db68df2356868fad5f6bfc2 Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Thu, 6 Aug 2026 16:34:22 +0200 Subject: [PATCH] Sync wiki from project files --- Codex-Project-Index.md | 1 + Repo-README.md | 48 +++++++++++++++- Repo-docs-INTERFACE-PATTERN-MIGRATION.md | 60 ++++++++++++++++++++ Repo-docs-POSTBOX-CONCEPT.md | 70 ++++++++++++++++++++++-- 4 files changed, 172 insertions(+), 7 deletions(-) create mode 100644 Repo-docs-INTERFACE-PATTERN-MIGRATION.md diff --git a/Codex-Project-Index.md b/Codex-Project-Index.md index 00bc215..d568b64 100644 --- a/Codex-Project-Index.md +++ b/Codex-Project-Index.md @@ -5,4 +5,5 @@ This page is generated from repository and product-directory project files. - [Repo-README](Repo-README) - `/mnt/DATA/git/govoplan-postbox/README.md` +- [Repo-docs-INTERFACE-PATTERN-MIGRATION](Repo-docs-INTERFACE-PATTERN-MIGRATION) - `/mnt/DATA/git/govoplan-postbox/docs/INTERFACE_PATTERN_MIGRATION.md` - [Repo-docs-POSTBOX-CONCEPT](Repo-docs-POSTBOX-CONCEPT) - `/mnt/DATA/git/govoplan-postbox/docs/POSTBOX_CONCEPT.md` diff --git a/Repo-README.md b/Repo-README.md index 71d8db4..c6a099f 100644 --- a/Repo-README.md +++ b/Repo-README.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-postbox/README.md`. > Origin: `repository`. @@ -25,7 +25,7 @@ This repository owns: normalized Identity, IDM, Organizations, and Core/Access contracts - API routes for postbox directory, messages, access checks, and administration - optional integration capabilities for campaign, files, portal, notification, and mail-facing workflows -- future WebUI package `@govoplan/postbox-webui` +- inbox and tenant administration WebUI package `@govoplan/postbox-webui` Core owns auth, tenants, RBAC evaluation, database/session primitives, module discovery, migrations, CSRF/API helpers, and shell layout. Identity owns @@ -55,6 +55,12 @@ Unit-specific addresses are resolved lazily and remain stable through vacancy and reassignment. Exact postboxes remain available for exceptional responsibilities or case/service contexts. +Subtree templates select an explicit Organizations structure and optional +hierarchical relation types. The administration UI can dry-run a draft against +the current organization and incumbency state, showing generated addresses, +vacancy, existing targets, collisions, and hierarchy diagnostics without +materializing data. + Users holding several functions may group selected postboxes into unified inbox views. These are query projections only: messages, address, read state, retention, and evidence remain attached to their source postboxes. @@ -79,3 +85,41 @@ Frontend package: ``` Platform RBAC, module capability contracts, and governance rules are documented in `govoplan-core/docs/`. + +The module's interface archetypes, consequence classes, contextual-help +contracts, and accessibility evidence are recorded in +[`docs/INTERFACE_PATTERN_MIGRATION.md`](docs/INTERFACE_PATTERN_MIGRATION.md). + +## Current implementation + +The first usable slice includes immutable template revisions, stable lazy +addresses, exact function-bound Postboxes, current IDM assignment access +decisions, vacancy status, idempotent producer delivery, source-preserving +message and attachment references, personal read/acknowledgement receipts, +unified inbox projections, access evidence, an inbox route, and tenant +administration. Grouping summaries expose batched total and unread counts for +currently visible sources. Published template revisions can also opt into bounded linked +copies through one explicit organization structure. Classification, producer, +retention, stop, depth, target-template, and target-function gates are frozen +at delivery time and exposed through delivery evidence and the routing dry-run +API. + +Vacancy escalation is a separate attention policy. It creates no personal +account grant: a durable route waits for its configured delay and then creates +an independently readable copy in the next frozen function Postbox. The +`govoplan.postbox.dispatch_routes` periodic Core worker drains due routes when +Celery beat and a worker consuming the `postbox` queue are enabled. + +Postboxes support `plaintext_v1` and an optional `server_envelope_v1` profile. +The latter stores message bodies as ciphertext through the Encryption +capability and fails closed on reads if that capability or key is unavailable. +Subjects, participants, routing, attachment references, and lifecycle metadata +remain observable. Existing externally produced ciphertext references remain +supported, but neither path is described as end-to-end encryption. + +Run focused checks with: + +```bash +/mnt/DATA/git/govoplan/.venv/bin/python -m unittest discover -s tests +cd webui && npm run test:ui-structure +``` diff --git a/Repo-docs-INTERFACE-PATTERN-MIGRATION.md b/Repo-docs-INTERFACE-PATTERN-MIGRATION.md new file mode 100644 index 0000000..f41dcfa --- /dev/null +++ b/Repo-docs-INTERFACE-PATTERN-MIGRATION.md @@ -0,0 +1,60 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-postbox/docs/INTERFACE_PATTERN_MIGRATION.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# Postbox Interface Pattern Migration + +This document records the bounded migration of Postbox-owned WebUI surfaces to +the GovOPlaN interface pattern language. Core owns shared controls and host +shells. Postbox owns function-bound addresses, messages, receipts, delivery +evidence, personal inbox projections, and reusable address templates. + +## Surface Inventory + +| Surface | Archetype | Consequence class | Contract | +| --- | --- | --- | --- | +| `/postbox` directory | Directory and hierarchy-context selector | Change query projection | Shared selection list, explicit assignment blocker, contextual help, guarded reload | +| `/postbox` messages | Searchable work queue | Read, acknowledge, reply, or author | Shared filters/pagination/status/alerts, explained unavailable actions, privacy-safe retained states | +| Message detail and composer | Record detail and consequential editor | Deliver institutional message | Source/function provenance, classification boundary, guarded draft, stable field help | +| Unified-view dialog | Personal configuration editor | Change or delete query projection | Shared dialog/toggle/confirmation; deletion never changes source messages or evidence | +| `postbox.admin.templates` | Versioned definition library | Publish or retire immutable template revision | Shared admin layout, durable consequence explanations, guarded editor, contextual help | +| Materialized Postbox administration | Repeated administration | Create or archive durable address | Organization/function selector, prerequisite blocker, destructive confirmation, retained-evidence explanation | +| `postbox.widget.inbox` | Dashboard summary | Navigate to unread work | Shared widget loading/error/list contract and localized accessible attachment metadata | + +## Consequence And Availability Rules + +- A Postbox address belongs to an organization function, not to an account. + Current effective IDM assignments determine access without changing the + durable message or address record. +- Publishing freezes an immutable template revision. Retiring a template stops + future revision and materialization work but leaves existing addresses + intact. +- Archiving an address stops new delivery while preserving messages, receipts, + access events, and delivery evidence. +- Unified inbox views are personal projections. Deleting one does not move or + delete source Postboxes, messages, acknowledgements, or evidence. +- Hierarchy copies are separate, bounded deliveries. Vacancy escalation is a + separately scheduled and auditable route, not an implicit personal grant. +- Withdrawal and expiry prevent future content access while retaining only the + metadata the current actor may inspect. Already exported or printed plaintext + cannot be retracted. +- Disabled actions state whether the blocker is loading, another operation, a + missing permission, a missing assignment, an unavailable message, or a + lifecycle constraint. + +## State And Accessibility Evidence + +The module uses Core admin/page shells, selection lists, pagination, dialogs, +confirmations, alerts, status badges, action blockers, contextual field help, +disabled reasons, and unsaved-change guards. Shared dialogs retain keyboard +focus and return behavior. Existing responsive workspace CSS keeps directory, +message list, and detail regions bounded and independently scrollable. + +English and German catalogues cover module metadata, accessible attributes, +workspaces, dialogs, fields, lifecycle states, and dashboard output. Dates use +the selected platform locale. Manifest topics publish stable route, surface, +field, blocker, privacy, and consequence references. Focused backend and WebUI +tests pin these contracts without importing optional sibling modules. diff --git a/Repo-docs-POSTBOX-CONCEPT.md b/Repo-docs-POSTBOX-CONCEPT.md index 04d0694..fc18216 100644 --- a/Repo-docs-POSTBOX-CONCEPT.md +++ b/Repo-docs-POSTBOX-CONCEPT.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-postbox/docs/POSTBOX_CONCEPT.md`. > Origin: `repository`. @@ -19,10 +19,13 @@ needed a role, process, portal, campaign, or service responsibility. It may look like an inbox for a message task or like a vault for content shared with the current holders of that responsibility; neither form is owned by one account. -The strategic target is an encrypted administrative postbox. The first -implementation may start with ordinary persisted messages, but the model must -not prevent later end-to-end encryption, role/function key epochs, signed -manifests, external-recipient tokens, or honest retraction semantics. The +The strategic target is an encrypted administrative postbox. The current +implementation supports ordinary persisted messages and an optional +server-readable Encryption envelope for message bodies. The model also retains +external ciphertext, wrapped-key, signed-manifest, external-recipient-token, +and key-epoch metadata needed for later independently reviewed E2EE profiles. +The server-envelope profile is not E2EE, and subjects, routing, participants, +and attachment references remain visible. The cross-module target architecture is recorded in `govoplan-core/docs/POSTBOX_E2EE_ARCHITECTURE.md`. @@ -143,6 +146,19 @@ scope, such as a unit type, structure, or subtree. Postbox resolves a stable unit-specific address from the tenant, template revision, concrete unit, concrete function, and optional case/service context. +Subtree scope is explicit about the Organizations structure and may restrict +the hierarchical relation types used within that structure. It does not infer +scope from the legacy `parent_id` when an administrator creates or revises a +template. This prevents an administrative, reporting, and project hierarchy +from being confused when they contain the same units. + +Before saving a draft, administrators can run a read-only impact preview. It +uses the same scope, function matching, address rendering, and incumbent rules +as materialization and reports ready targets, already materialized addresses, +vacancies, collisions, cycles, depth limits, and ambiguous paths. The preview +does not create a template, address, Postbox, or delivery. A large result is +bounded in the UI while its aggregate counts remain visible. + Addresses should be resolved lazily and idempotently rather than eagerly creating empty containers for every unit. They remain durable through vacancy and reassignment. A delivery snapshots the template revision and normalized @@ -159,6 +175,16 @@ unified inbox views and keep other responsibilities separate. Grouping is a query projection only. It never merges source containers, messages, read or acknowledgement state, retention, encryption keys, or audit evidence. +The optional Tasks module may aggregate available unread Postbox messages into +the common work inbox. This is a current, permission-rechecked projection of a +personal read receipt, not a copied task or message. Reading the message in +Postbox removes the projection; Postbox remains authoritative for content, +access, acknowledgement, reply, retention, and evidence. + +Grouping summaries calculate total and unread counts over the currently +visible source Postboxes in one tenant-bounded query. Hidden sources retained +for later reassignment do not leak counts into the projection. + Every item and action continues to show the source function, unit, postbox, assignment/delegation context, and classification. Policy may require some postboxes to remain separate. @@ -183,6 +209,24 @@ Vacancy is a visible delivery/attention state rather than an automatic grant to an unrelated personal account. Policy may trigger a bounded escalation after a delay. +The implemented policy keeps the three semantics separate: + +- `linked_copy` can target the nearest matching ancestor or every bounded + matching ancestor in one selected structure. +- `attention` currently supports delayed vacancy escalation over the remaining + delivery-time target snapshot. +- `shared_visibility` remains explicitly disabled until its access and + encryption semantics are implemented. + +Routing is off unless an immutable template revision enables it and supplies a +target template, target function type, producer allowlist, classification +allowlist, depth, and structure. Optional relation, stop-unit, stop-unit-type, +expiry, and maximum-retention gates narrow the route further. The dry-run API +returns blocked and unavailable candidates without materializing addresses. +Delivery materializes only frozen candidates, stores path-edge provenance, and +creates source-preserving copies with independent read and acknowledgement +receipts. + ## Campaign Distribution Campaign can use Postbox as an explicit delivery channel through @@ -319,6 +363,22 @@ The WebUI should start as an administration and inbox surface: Campaign, files, portal, and mail behavior should arrive as optional integrations after the core postbox model is stable. +### Current content-protection profile + +An exact Postbox or template revision may select `server_envelope_v1` and an +Encryption vault. New locally authored and delivered message bodies are then +stored in `body_ciphertext` with an owner-bound envelope reference; clear body +text is not persisted. Reads ask the optional `encryption.content_cipher` +capability to open the exact tenant, message, and envelope tuple. Missing +Encryption, a lost deployment key, a destroyed vault key, ciphertext tampering, +or a mismatched resource causes a fail-closed read. + +Plaintext Postboxes continue to work without Encryption. A protected Postbox +cannot silently fall back to plaintext. Database recovery of protected messages +requires Postbox and Encryption tables from the same consistency point plus the +matching provider/deployment key. Hierarchy-routed copies retain the source +envelope reference rather than decrypting and re-encrypting during routing. + ## E2EE Readiness Checklist Before the data model is considered stable, verify that it can represent: