Mirrored from
/mnt/DATA/git/govoplan-postbox/docs/POSTBOX_CONCEPT.md. Origin:repository. Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
Postbox Concept
Purpose
GovOPlaN Postbox provides in-platform postboxes that are addressable containers for messages, files, workflow evidence, and operational handoff. They can be used internally, exposed through portals, and connected to campaign workflows.
The key distinction from a mailbox is ownership. A mailbox is usually bound to a login, user credential, or external mail account. A GovOPlaN postbox is bound to platform context: organization, role, process, portal, campaign, or service responsibility.
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
cross-module target architecture is recorded in
govoplan-core/docs/POSTBOX_E2EE_ARCHITECTURE.md.
Role-Organization-Bound Access
The special access pattern is a postbox linked to an organizational unit and one or more roles. A person can access that postbox while their identity has an effective matching role in that organizational unit.
Example:
- Organizational unit:
District Office North - Required role:
Case Clerk - Postbox:
District Office North / Case Clerk Intake
Any identity currently holding the Case Clerk role for District Office North can see the postbox. When the role is removed or expires, access disappears without moving messages or reassigning a mailbox.
This makes postboxes useful for responsibilities that outlive individuals:
- intake desks
- role-based service queues
- campaign sender or response desks
- portal message inboxes for organizational responsibilities
- file or evidence drops linked to a role in an organization
Authorization Model
Postbox authorization should be derived from access-owned identity and role data through core/access contracts. The postbox module stores postbox bindings and postbox-specific permissions, but it should not duplicate membership, group, or role resolution.
The minimum authorization inputs are:
- postbox id
- tenant id
- organizational unit id
- required role id or role key
- actor identity id
- current effective role assignments from the access module
- optional explicit administrative grants for postbox administration
The expected result is a narrow access decision:
- can discover
- can read
- can send or reply
- can attach or link files
- can administer bindings
Access changes must be auditable because a person can gain or lose postbox visibility through role assignment changes rather than direct postbox membership edits.
Domain Objects
The initial domain model should stay small:
Postbox: the addressable container.PostboxBinding: the binding to organization, role, portal, campaign, service, or explicit context.PostboxMessage: a platform-native message or message reference.PostboxParticipant: normalized sender, recipient, author, or actor reference.PostboxAttachmentRef: reference to a file, evidence item, generated campaign artifact, or external attachment.PostboxAccessEvent: auditable record of access-affecting changes and sensitive actions.
Messages and files should be linked by stable ids and typed references. The postbox module should not import file, mail, or campaign internals.
Capability Boundaries
Postbox should expose narrow capabilities through core:
postbox.directory: find postboxes visible to an actor.postbox.access: answer access decisions for a postbox/action pair.postbox.messages: create, list, and read postbox messages through DTOs.postbox.delivery: accept messages or delivery artifacts from other modules.postbox.evidence: link durable evidence references without owning the evidence store.
Optional consumers:
- Campaign can use postboxes for campaign sender context, reply intake, review queues, and role-bound access to campaign artifacts.
- Files can expose file references to a postbox when the actor's role grants access.
- Portal can show portal-facing postboxes without owning the postbox access model.
- Mail can bridge external mailbox delivery into postboxes when configured, without making postboxes mailbox-bound.
Operational Rules
- Current role state controls current access.
- Historical message records remain durable even when no current person holds the role.
- Administration of bindings should require explicit postbox administration permission plus access/RBAC authority for the target organization.
- Sensitive access decisions and binding changes should emit audit events.
- Retention rules should be postbox-owned but able to reference campaign, file, and portal provenance.
- Expiry, withdrawal, and retraction UI must distinguish future access control from already fetched or decrypted plaintext.
- Message metadata should preserve room for ciphertext manifests, wrapped keys, key epochs, recipient device references, and external capability tokens even before full E2EE ships.
First Implementation Shape
The first implementation should define the backend manifest, permissions, DTOs, and migrations before building rich UI. A minimal API can then support directory lookup, access checks, message creation, message listing, and binding administration.
The WebUI should start as an administration and inbox surface:
- postbox directory
- role-bound access explanation
- message list and message detail
- binding editor for organization and role links
- audit-visible administrative actions
Campaign, files, portal, and mail behavior should arrive as optional integrations after the core postbox model is stable.
E2EE Readiness Checklist
Before the data model is considered stable, verify that it can represent:
- message or attachment ciphertext references
- signed manifest references
- recipient, role, or function key wrapping records
- key epoch and device-key references
- key-fetch/access audit events
- external recipient token state
- expiry and withdrawal state separate from deletion
- retention state that can operate without decrypting content