Security and Credential Lifecycle

School Server security has several distinct trust layers. Keep them separate so a convenience change in one layer does not silently weaken another.

Trust layers

1. Local runtime secrets — database, JWT, data-encryption and service credentials.
2. LAN trust — appliance-local CA and School Server certificate used by managed browsers.
3. Cloud machine identity — per-appliance API key, HMAC secret, credential generation and appliance lifecycle.
4. Authority policy — which server/Cloud side may write each governed school domain.
5. Release trust — checksums/signatures/manifest/image identity for installed software.

Zero-touch identity model

A normal field appliance starts without tenant, school or site UUIDs in .env.school.

Tenant/school identity is determined by the Cloud-issued code. Site identity is generated by the appliance and then bound to the Cloud appliance record.

Durable SITE_ID

After commissioning, SITE_ID is stable appliance identity. Preserve it across:

• reboot;
• normal software update;
• network/IP change;
• certificate renewal;
• credential rotation;
• same-appliance restore where the identity is intentionally retained.

A replacement School Server generates a new site identity and goes through the governed replacement lifecycle; do not copy the old site's identity onto new hardware merely to appear continuous.

DATA_ENCRYPTION_SECRET

This key protects sensitive local enrollment/runtime state and setup capabilities. Requirements:

• high entropy;
• independent from JWT_SECRET;
• securely backed up under infrastructure/security custody;
• preserved across update and same-state restore;
• never browser-visible;
• never pasted into tickets/chat;
• not casually rotated without a re-encryption/recovery design.

A disaster restore with the wrong key can leave encrypted machine credentials unreadable even if the database itself restored successfully.

Appliance-local CA and TLS keys

runtime/tls/ contains the stable local CA plus the current School Server key/certificate.

• CA private key is sensitive infrastructure material.
• Managed client devices trust the CA certificate, not an ad-hoc browser exception.
• The short-lived server certificate can renew while the local CA remains stable.
• Loss of the CA can create a client trust migration even if school data is otherwise intact.

Protect the CA/key according to the site's restore model.

One-time enrollment code

The MNX... code is temporary provisioning material. It is not the permanent machine credential.

Cloud validates its expiry and intended school/appliance lifecycle. The code can be safely reissued for the same unconfirmed appliance/replacement candidate after an interrupted commissioning flow; abandoned temporary exchange credentials/sessions are cancelled rather than creating uncontrolled duplicate machines.

Do not extend a short-lived human code into a permanent backdoor. Recovery uses the governed reissue/confirmation model.

Two-phase machine credential exchange

Power loss can occur after Cloud allocates credentials but before the appliance confirms durable local storage. The hardened exchange therefore separates:

1. temporary credential allocation/escrow;
2. local durable encrypted storage;
3. HMAC-authenticated machine confirmation.

The browser is outside the long-lived credential path.

Machine request protection

Connected machine requests are protected by:

• enrolled appliance API-key authentication;
• independent HMAC secret;
• HMAC SHA-256 signature over the request body;
• bounded timestamp/replay window;
• nonce replay protection;
• tenant/school/site/appliance scope;
• compatibility checks where the canonical endpoint requires them;
• per-school/domain authority enforcement before governed changes are applied.

If replay/authority verification cannot be safely completed, synchronization/write authorization fails closed instead of downgrading to an ungoverned path.

Clock security dependency

Because machine authentication uses timestamps, large system-clock drift can reject otherwise valid requests. The installer configures/inspects host time sync and the health service measures NTP offset.

Do not respond to clock-skew errors by disabling signature/replay protection. Fix the clock/NTP path.

Credential rotation

Use rotation when the physical School Server remains valid but its Cloud machine credential should change—for policy, suspected exposure or controlled recovery.

The rotation path must preserve appliance identity and local data. The technician receives only the governed temporary rotation/re-authorization material, not permanent plaintext machine secrets.

After rotation, verify the current appliance can synchronize and the superseded credential no longer remains an uncontrolled long-term writer.

Revocation

Revoke an appliance identity when it must no longer authenticate to Cloud—for example theft, retirement, compromise or completed replacement.

Revocation is a Cloud machine-auth decision. It does not intentionally wipe local PostgreSQL/MinIO. A revoked physical server may still have sensitive local data and must be handled under the site's incident/decommission policy.

Replacement and write fencing

A replacement candidate is not a second primary. It remains write-fenced until the guarded cutover. If the old primary is reachable, it must acknowledge a source write fence before authority transfer.

For a dead source, the override requires explicit physical decommission/offline confirmation and a healthy ready candidate. Never use the override while the old School Server could still be accepting school transactions.

Per-school/domain authority

General API authorization is not sufficient to decide which node owns a school transaction. Cloud and local write paths also enforce the registered school/domain authority.

Unknown or unresolved governed domains fail closed. This prevents a route that was forgotten in the mapper from becoming an accidental bypass.

Secret handling by role

Material	Cloud operator	Field technician	School user/browser
One-time MNX... code	Issues/transfers	Uses temporarily	Setup input only
Tenant/school UUID	Cloud internal/admin context	Not required in normal install	Not a setup credential
Generated site identity	Fleet-visible after claim	No manual generation required	Not a secret
Appliance API key/HMAC	No normal plaintext handling	No	Never
DATA_ENCRYPTION_SECRET	Infra/security custody	Only if explicitly responsible for host secrets	Never
Appliance CA certificate	May be distributed	Installs/trusts on managed clients	Public trust certificate
Appliance CA private key	No routine handling	Host/security custody only	Never
DB/MinIO passwords	Infra/field secret custody	If responsible for install	Never

Security acceptance checklist

• Normal setup required only the one-time code, not permanent machine secrets.
• Stable site identity was generated/persisted before machine confirmation.
• Browser network/UI never exposes the API key/HMAC secret.
• DATA_ENCRYPTION_SECRET is independent and recoverable.
• Managed clients trust the appliance CA without warning bypasses.
• Host clock/NTP posture is acceptable.
• Signed requests reject replay/scope violations.
• Authority is positively established for governed school writes.
• Candidate replacement remains fenced before cutover.
• Revoked/retired server cannot resume Cloud machine authentication as primary.

For operational recovery, see Backup, Restore, and Server Replacement and Field Troubleshooting.