Metadata-Version: 2.4
Name: govoplan-postbox
Version: 0.1.15
Summary: Function-bound institutional postboxes for GovOPlaN.
Author: GovOPlaN
License-Expression: AGPL-3.0-or-later
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: govoplan-core>=0.1.15

# govoplan-postbox

<!-- govoplan-repository-type:start -->
**Repository type:** module (domain).
<!-- govoplan-repository-type:end -->

GovOPlaN Postbox provides platform-owned postboxes for internal work, portals,
campaign flows, and function-bound organizational communication.

## Ownership

This repository owns:

- backend module manifest `postbox`
- postbox permissions and policy checks
- postbox, binding, message, participant, attachment-reference, and audit-facing data models
- function-organization-bound access resolution for postboxes through
  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
- 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
identities and account links. Organizations owns units, structures, function
types, and concrete functions. IDM owns effective identity-to-function
assignments, delegation, and acting-for facts. Access owns generic application
roles, permissions, and administrative RBAC surfaces.

## Function-bound postboxes

A function-bound postbox has a stable institutional address linked to an
organizational unit and one or more functions. It can exist with zero, one, or
several current incumbents. A person can access it only while their identity
has an effective assignment or time-bounded delegation in that organizational
context and their account may perform the relevant Postbox action. Access is
not tied to a login mailbox, personal email address, static user assignment, or
function-to-RBAC-role mapping.

When the assignment changes, postbox access and encrypted key grants change
with it. The postbox keeps durable content and evidence history through
vacancy, hand-over, and delegation; multiple incumbents receive independently
auditable access. Revocation prevents future platform key access but cannot
erase plaintext already fetched or exported.

Reusable Postbox templates may target a function type and organization scope.
Unit-specific addresses are resolved lazily and remain stable through vacancy
and reassignment. Exact postboxes remain available for exceptional
responsibilities or case/service contexts.

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.

Hierarchy propagation is off by default. Explicit copy, attention/escalation,
and shared-visibility rules are distinct, bounded, classification-aware, and
snapshotted when a message is delivered.

## Module integration

Backend entry point:

```toml
[project.entry-points."govoplan.modules"]
postbox = "govoplan_postbox.backend.manifest:get_manifest"
```

Frontend package:

```text
@govoplan/postbox-webui
```

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. 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
```
