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.

Invariants

Every installation remains authoritative for its tenants, identities, policies, keys, records, and local mappings.
A remote identity or permission never becomes a local authorization claim.
Every exchange declares purpose, legal/organizational basis, classification, minimization, retention expectation, and permitted onward use.
Every object reference identifies origin instance, owner tenant, object type, object ID, exact revision, and source-authority mode.
Payloads and receipts are signed; sensitive transports use mutually authenticated encrypted channels.
Acceptance, rejection, outcome unknown, retry, revocation, correction, and reconciliation are durable states.
Local policy may reject or narrow a remote request. It cannot silently claim to have accepted an effect that did not occur.
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

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

Pair two disposable installations with independent tenants, keys, and policies.
Exchange signed descriptors and approve only the Postbox delivery profile.
Deliver one Campaign message to a remote function-bound Postbox.
Prove replay safety, rejection, timeout/outcome unknown, retry, acknowledgement, correction, key rotation, and revoked trust.
Export the complete evidence bundle and restore both sides from backup.
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.

7.7 KiB Raw Blame History