govoplan-postbox/docs/POSTBOX_CONCEPT.md

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.

Function/Role-Organization-Bound Access

The special access pattern is a postbox linked to an organizational unit and one or more roles or functions. A person can access that postbox while their account has an effective matching function assignment in that organizational unit, or while a matching function maps to one of the required roles.

Example:

• Organizational unit: District Office North
• Required role: Case Clerk
• Postbox: District Office North / Case Clerk Intake

Any identity/account currently holding the Case Clerk function or a mapped role for District Office North can see the postbox. When the function, delegation, or role mapping 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 function id, role id, or role key
• actor identity id
• current effective function assignments, delegations, and roles 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.

Runtime integration must use the access kernel capabilities:

• access.semanticDirectory to inspect identity/account/function facts.
• access.explanation to attach identity/account/function/role/right provenance to access decisions.

Postbox must not import access ORM models or duplicate function/role resolution. Acting-in-place access should require an explicit selected acting context once Access exposes that runtime selector.

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