Amy-Term
Federation Trust Model
Security model for distributing terminology artefacts across central and regional deployments, including offline environments.
Baseline assumption: Federation is a controlled ecosystem (central authority distributes to known regional nodes).
The baseline cryptographic model uses
HS256 (HMAC-SHA256) with a shared secret distributed through secure operational channels.
1. Purpose
Federation enables controlled distribution of terminology artefacts between central and regional nodes, including offline transfer via ZIP/USB. This document defines the trust model, signing policy, verification defaults, and key rotation guidance for federation bundles.
2. Roles
| Node type | Primary responsibilities |
|---|---|
| Central | Authoritative source; creates and signs export bundles; defines signing policy; governs namespaces and release processes. |
| Regional | Verifies signatures; applies bundles to local store; maintains local audit trail; enforces namespace policy and acceptance rules. |
| Offline/air-gapped site | Receives transferred bundles (USB/ZIP); applies bundles under the same verification policy; logs application events for later reconciliation. |
Operational ownership
- Central: signing key custodianship, rotation, and incident response (key compromise).
- Regional: secure storage of verification keys, acceptance policy enforcement, and audit review.
3. Assets to protect
- Integrity: bundles must not be modified in transit without detection.
- Authenticity: regional nodes must know the bundle came from an authorised central authority.
- Replay controls: prevent re-applying older bundles where policy forbids it (e.g., monotonic versioning).
- Namespace isolation: bundles are scoped; nodes apply only allowed namespaces.
HS256 note: HS256 provides integrity + authenticity within a shared-secret trust boundary.
It does not create a public trust anchor. For multi-party ecosystems or external trust anchors, use asymmetric signing.
4. Bundle signing
Algorithm
- HMAC-SHA256 (
HS256)
Canonicalisation
Signing must be performed on a deterministic representation (canonical JSON) to prevent signature mismatch due to formatting differences. Canonicalisation should be applied before computing the HMAC.
Signing and distribution flow (conceptual)
1) Central builds bundle (canonical JSON) 2) Central signs bundle with HS256 shared secret 3) Central distributes bundle via pull endpoint or offline export (ZIP/USB) 4) Regional verifies signature using accepted secret(s) 5) Regional applies artefacts to local store and records receipts/audit logs
5. Verification and acceptance policy
Default policy (recommended)
- Reject unsigned bundles by default.
- Reject invalid signature always.
- Reject wrong namespace (bundle namespace not allowed on this node).
- Reject older version if your policy enforces monotonic upgrades.
Acceptance checklist (operator)
# Before applying a federation bundle: # - Signature present AND valid # - Bundle namespace allowed on this node # - Bundle id not previously applied (replay protection) # - Version meets policy (e.g., not older than current) # - Apply under admin-only action, log receipts
Emergency override: Allowing unsigned bundles should be a manual, time-bound, audited override
(e.g., disaster recovery). If enabled, log the operator, rationale, and approval reference.
6. Key management
Storage
- Keys are stored outside source code (environment variables or secret manager).
- Keys must never be committed to version control.
- Access to signing keys is restricted to central-node ops staff.
Distribution
- Distribute shared secrets through a secure channel (for example: password manager with access control; encrypted out-of-band transfer).
- Maintain a register of which regional nodes have received which key version.
Key handling rules (copy/paste)
# Key handling rules # - Never store secrets in Git # - Restrict signing keys to central ops # - Regional nodes need verification keys (same secret for HS256) # - Use per-environment keys (dev/test/prod are different) # - Audit access to secret stores
7. Key rotation
When to rotate
- At least annually (policy-driven).
- Immediately on suspected compromise.
- On staff turnover affecting key custodians.
Overlap strategy (recommended)
- Maintain a short overlap period where regional nodes accept both current and previous key for verification.
- Central signs with the new key after regional nodes are prepared.
- Remove the previous key after the overlap window ends.
Rotation runbook (high level)
1) Generate new HS256 secret (central) 2) Distribute new secret to authorised regional operators via secure channel 3) Configure regional nodes to accept BOTH old + new (verification) 4) Switch central signing to the new secret 5) Monitor successful applications during overlap window 6) Remove old secret after overlap window ends
8. Signing policy (recommended baseline)
- Central signs federation exports by default.
- Regional nodes require signed bundles by default.
- Unsigned bundles permitted only via audited, manual override.
- Bundles are namespace-scoped; nodes apply only allowed namespaces.
Governance tip: Align federation signing with your release process: approve, sign, distribute, apply, verify.
The signing operation becomes the “publication step” that creates a verifiable artefact for audit.
9. Audit and controls
- Federation capture/export is an admin-only action.
- Application of a bundle is an admin-only action on regional nodes.
- Log bundle id, namespace, version, hash, verification outcome, operator identity, and timestamp.
- Retain audit logs according to Controller policy.
10. Future hardening (roadmap)
- Asymmetric signing (Ed25519 / ES256) for multi-party ecosystems with distinct trust anchors.
- Key identifiers (kid) and a key registry for smoother rotations and multi-key verification.
- Replay protection via monotonic sequence numbers or signed release manifests.
- Policy bundles (signed acceptance rules per region) to enforce distribution constraints consistently.
Document: federation_trust_model.html