# System Updater

Admin → System Updater accepts a trusted, versioned Exams.fit core upgrade ZIP. This is separate from educational-content import ZIPs.

## Safety sequence

1. Verify the administrator session and CSRF token.
2. Validate ZIP paths, package identity, version compatibility and SHA-256 for every payload and migration.
3. Reject downgrade packages, path traversal, protected data targets and destructive SQL.
4. Create a full SQL backup and a recovery ZIP containing every core file that will change.
5. Enable a short maintenance response for public requests.
6. Replace allowlisted core files through temporary files and atomic rename.
7. Apply only additive, idempotent migrations and run required-file/version health checks.
8. Clear cache, record an audit/history entry and remove maintenance mode.
9. If an error occurs, automatically restore changed files. The SQL backup is retained.

The updater never targets `config.php`, `.env`, `uploads/`, operational `storage/`, or `storage/install.lock`. File rollback deliberately preserves additive database structures so newer content is not deleted.

## Upgrade ZIP format

The root contains `update.json`, `payload/`, and optional `migrations/`. `update.json` uses:

```json
{
  "package_id": "EXAMSFIT-CORE",
  "version": "3.2.0",
  "minimum_version": "3.1.0",
  "maximum_version": "3.1.99",
  "files": [{"path": "app/example.php", "sha256": "64-lowercase-hex-characters"}],
  "migrations": [{"file": "migrations/004_example.sql", "sha256": "64-lowercase-hex-characters"}]
}
```

Install only packages obtained from a trusted source. Checksums detect corruption inside the package; they do not prove who created an untrusted ZIP.
