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

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

The persistence model reserves ciphertext manifests, wrapped keys, key epochs,
expiry, and withdrawal state. The active profile remains `plaintext_v1`; the
module does not claim end-to-end encryption until the history, recovery, and
handover policy choices in the security issues are resolved.

Run focused checks with:

```bash
/mnt/DATA/git/govoplan/.venv/bin/python -m unittest discover -s tests
cd webui && npm run test:ui-structure
```