156 lines
7.7 KiB
Markdown
156 lines
7.7 KiB
Markdown
# Federated GovOPlaN Architecture
|
|
|
|
## Purpose
|
|
|
|
Federation lets autonomous GovOPlaN installations exchange data,
|
|
configuration, work, messages, records, and evidence without sharing a database
|
|
or surrendering local policy. It is institution-to-institution cooperation,
|
|
not multi-tenancy across an untrusted network.
|
|
|
|
The first implementation should prove a bounded exchange between two
|
|
installations. A new federation module is not justified until the shared
|
|
protocol has at least two independent consumers. Core owns neutral envelopes
|
|
and trust contracts; Connectors owns transport providers; domain modules own
|
|
the objects and effects they exchange.
|
|
|
|
Implementation is tracked in
|
|
[GovOPlaN #41](https://git.add-ideas.de/GovOPlaN/govoplan/issues/41).
|
|
|
|
## Invariants
|
|
|
|
1. Every installation remains authoritative for its tenants, identities,
|
|
policies, keys, records, and local mappings.
|
|
2. A remote identity or permission never becomes a local authorization claim.
|
|
3. Every exchange declares purpose, legal/organizational basis, classification,
|
|
minimization, retention expectation, and permitted onward use.
|
|
4. Every object reference identifies origin instance, owner tenant, object type,
|
|
object ID, exact revision, and source-authority mode.
|
|
5. Payloads and receipts are signed; sensitive transports use mutually
|
|
authenticated encrypted channels.
|
|
6. Acceptance, rejection, outcome unknown, retry, revocation, correction, and
|
|
reconciliation are durable states.
|
|
7. Local policy may reject or narrow a remote request. It cannot silently claim
|
|
to have accepted an effect that did not occur.
|
|
8. Federation works asynchronously and can exchange signed offline bundles
|
|
where continuous connectivity is unavailable.
|
|
|
|
## Trust Domains
|
|
|
|
An instance publishes a signed, versioned federation descriptor containing:
|
|
|
|
- stable instance and operator identity;
|
|
- supported protocol and schema versions;
|
|
- signing and transport key identifiers with rotation history;
|
|
- accepted object and exchange profiles;
|
|
- endpoint locations and size/rate limits;
|
|
- support, incident, revocation, and data-protection contacts;
|
|
- evidence and conformance references.
|
|
|
|
Pairing is a two-sided administrative workflow. Each side verifies the other,
|
|
maps the remote institution to a local trusted-party record, selects permitted
|
|
profiles and purposes, sets policy ceilings, and records approvals. Trust is
|
|
directional and profile-specific; trusting signed Postbox delivery does not
|
|
automatically permit case transfer or configuration import.
|
|
|
|
## Exchange Envelope
|
|
|
|
Every request, response, receipt, correction, and revocation uses one neutral
|
|
envelope with:
|
|
|
|
- message ID, correlation ID, causation ID, creation and expiry;
|
|
- origin and destination instance/institution/tenant references;
|
|
- real actor and represented institutional capacity where disclosure is
|
|
permitted;
|
|
- exchange profile and semantic schema version;
|
|
- exact domain object references and content digests;
|
|
- purpose, legal basis, classification, data categories, retention expectation,
|
|
onward-transfer constraint, and subject notice status;
|
|
- requested action and idempotency key;
|
|
- encryption recipients and signature chain;
|
|
- attachment/object manifests rather than unbounded embedded blobs;
|
|
- previous-envelope references for correction, replacement, or revocation.
|
|
|
|
The envelope is evidence, not a universal domain object. Each owner validates
|
|
and imports or links its own payload.
|
|
|
|
## Exchange Profiles
|
|
|
|
| Profile | First owners | Behavior |
|
|
| --- | --- | --- |
|
|
| Postbox delivery | Postbox, Campaign, Notifications | Address or derive a remote function-bound postbox, obtain acceptance receipt, and track acknowledgement where permitted |
|
|
| Case handoff | Cases, Parties, Services, Workflow Engine | Offer exact context and evidence; destination accepts into a new local case and returns the mapping |
|
|
| Record transfer | Records, Files, DMS, Audit | Transfer or offer a signed record package with file-plan, metadata, content digests, holds, and disposition constraints |
|
|
| Decision/evidence reference | Decisions, Committee, Audit | Publish a protected exact outcome or verifiable reference without transferring unrelated case content |
|
|
| Data product publication | Datasources, Dataflow, Reporting | Publish immutable governed materializations with schema, quality, freshness, lineage, and use constraints |
|
|
| Configuration package | Core, Policy, Views, Workflow, Forms, Templates | Exchange signed definitions; destination assesses compatibility, maps values, derives locally, and never imports secrets |
|
|
| Search discovery | Search and domain providers | Return permission-filtered metadata or a handoff link; never expose raw remote indexes as local authority |
|
|
|
|
## State Machine
|
|
|
|
```text
|
|
draft -> authorized -> queued -> transmitted -> received
|
|
| |
|
|
v v
|
|
outcome_unknown rejected
|
|
|
|
|
received -> validating -> accepted -> applied -> acknowledged
|
|
| | |
|
|
v v v
|
|
rejected accepted_ reconciled
|
|
pending
|
|
```
|
|
|
|
Acceptance means the destination durably owns the received intent. It does not
|
|
mean the requested domain effect completed. Receipts distinguish transport,
|
|
validation, acceptance, application, and human acknowledgement.
|
|
|
|
## Conflict And Autonomy
|
|
|
|
- Incoming native objects become local references, mirrors, or newly owned
|
|
objects according to the profile. They do not overwrite local authority by
|
|
ID coincidence.
|
|
- Local mappings are effective-dated and auditable.
|
|
- Corrections create a linked revision. They do not erase what the destination
|
|
previously observed.
|
|
- Revocation is a request and evidence event; the destination applies its own
|
|
legal and retention rules.
|
|
- Configuration imports use assessment and derivation. A remote package cannot
|
|
weaken local policy or install code implicitly.
|
|
- A disconnected partner remains a visible pending/failed state; work can be
|
|
rerouted through an approved alternative channel.
|
|
|
|
## Security And Privacy
|
|
|
|
- Use mTLS for paired online transports and signed envelopes for end-to-end
|
|
origin evidence.
|
|
- Encrypt payload objects for the destination, with key rotation and outcome-
|
|
unknown recovery; transport encryption alone is insufficient for queued
|
|
bundles.
|
|
- Do not put bearer credentials, local permission scopes, or reusable secrets
|
|
in an exchange.
|
|
- Rate-limit and size-bound discovery and transfer; quarantine unknown schemas
|
|
and active content.
|
|
- Evaluate current local authorization at every effect even when the envelope
|
|
describes historical authority.
|
|
- Log metadata separately from protected content so operators can reconcile
|
|
without broad content access.
|
|
- Subject access, correction, restriction, legal hold, and deletion requests
|
|
become federated workflows with local decisions and receipts, not remote
|
|
direct database operations.
|
|
|
|
## First Reference Proof
|
|
|
|
1. Pair two disposable installations with independent tenants, keys, and
|
|
policies.
|
|
2. Exchange signed descriptors and approve only the Postbox delivery profile.
|
|
3. Deliver one Campaign message to a remote function-bound Postbox.
|
|
4. Prove replay safety, rejection, timeout/outcome unknown, retry,
|
|
acknowledgement, correction, key rotation, and revoked trust.
|
|
5. Export the complete evidence bundle and restore both sides from backup.
|
|
6. Add configuration-package exchange only after the delivery proof passes.
|
|
|
|
The result is a provider-neutral federation contract. A future dedicated
|
|
module becomes appropriate only when pairing, trust administration, exchange
|
|
queues, and evidence have a lifecycle independent of Connectors and the first
|
|
domain owner.
|