diff --git a/docs/POSTBOX_BACKLOG.md b/docs/POSTBOX_BACKLOG.md deleted file mode 100644 index 9be1f5b..0000000 --- a/docs/POSTBOX_BACKLOG.md +++ /dev/null @@ -1,27 +0,0 @@ -# Postbox Backlog - -## P1 Immediate - -- [ ] Define the `postbox` backend manifest, permissions, module metadata, and capability names. -- [ ] Design the postbox, binding, message, participant, attachment-reference, and audit-event data model. -- [ ] Implement role-organization-bound access checks through core/access contracts. -- [ ] Add API DTOs and routes for postbox directory, access checks, message listing, message creation, and binding administration. -- [ ] Create focused tests for access changes when role assignments are granted, revoked, or expire. - -## P2 Module Integration - -- [ ] Define optional campaign integration for sender context, response intake, and artifact handoff. -- [ ] Define optional files integration for postbox-visible file and evidence references. -- [ ] Define optional portal integration for portal-facing role-bound postboxes. -- [ ] Define optional mail bridge semantics without making postboxes login-bound mailboxes. - -## P2 WebUI - -- [ ] Build the postbox administration route contribution and navigation metadata. -- [ ] Build an inbox view for visible postboxes, messages, and role-bound access explanation. -- [ ] Build a binding editor for organization and role links with audit-visible changes. - -## P3 Governance - -- [ ] Document retention, audit, and privacy rules for postbox messages and evidence references. -- [ ] Document migration ownership and compatibility imports while postbox code is extracted from core if needed. diff --git a/docs/POSTBOX_CONCEPT.md b/docs/POSTBOX_CONCEPT.md index 5a4ce3e..e8ee430 100644 --- a/docs/POSTBOX_CONCEPT.md +++ b/docs/POSTBOX_CONCEPT.md @@ -6,9 +6,19 @@ GovOPlaN Postbox provides in-platform postboxes that are addressable containers 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. -## Role-Organization-Bound Access +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`. -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. +## 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: @@ -16,7 +26,10 @@ Example: - 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. +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: @@ -35,9 +48,10 @@ The minimum authorization inputs are: - postbox id - tenant id - organizational unit id -- required role id or role key +- required function id, role id, or role key - actor identity id -- current effective role assignments from the access module +- 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: @@ -50,6 +64,16 @@ The expected result is a narrow access decision: 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: @@ -87,6 +111,11 @@ Optional consumers: - 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 @@ -101,3 +130,16 @@ The WebUI should start as an administration and inbox surface: - 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