Hermes Hub — Auto-Update & Integrity Architecture

1. Overview

Hermes Hub includes an autonomous, fail-safe update engine designed to safely upgrade the application while strictly protecting user credentials, configurations, and active sessions.

2. Security Invariants

Cryptographic Verification: Every downloaded package is verified against a SHA-256 digest before any files are unpacked.
Hermetic Staging: Update packages are downloaded to %LOCALAPPDATA%\hermes\updates\staging and never overwrite active executing binaries directly.
Zero Secret Ingestion: Updates NEVER overwrite user OAuth tokens, API keys, router_profiles.yaml, hub_settings.json, or router_state.json.
Zero Hardcoded Developer PATs: The updater utilizes versioned release manifests and signed release asset endpoints without storing privileged credentials in the client application.

3. Update Manifest Schema (`update_manifest.json`)

{
  "version": "0.1.2",
  "channel": "stable",
  "minimum_hermes_version": "0.20.0",
  "published_at": "2026-08-20T17:00:00Z",
  "package_url": "https://github.com/ochenstarik-ui/hermes-hub/releases/download/v0.1.2/hermes-hub-0.1.2.zip",
  "sha256": "4b2e8d9a1f3c5e7b8a9d0c2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a",
  "release_notes_url": "https://github.com/ochenstarik-ui/hermes-hub/releases/tag/v0.1.2",
  "changelog": "Stabilization fixes, P0 blocker resolutions, and performance improvements."
}

4. Rollback & Fail-Safe Protocol

Pre-Update Backup: The updater creates a complete snapshot of src/, assets/, config/, and launcher/ in %LOCALAPPDATA%\hermes\updates\backup_prev.
Post-Update Syntax & Import Verification:
- py_compile is executed across all unpacked .py modules.
- An isolated Python sub-process verifies import integrity (from antigravity_provider.version import __version__).
Automatic Rollback: If syntax errors, import failures, or process crashes are detected, the updater immediately restores the previous working snapshot from backup_prev and notifies the user:

"Обновление не удалось. Выполнен автоматический откат к предыдущей версии."

5. Verification Suite

The update and rollback mechanisms are covered by automated unit and integration tests in tests/test_updater.py:

test_version_comparison: Validates semantic version precedence.
test_sha256_verification: Validates cryptographic checksum calculations.
test_bad_hash_rejection: Validates immediate rejection of corrupted/tampered payloads.
test_updater_rollback_on_failure: Validates automatic snapshot rollback on broken syntax.
test_dogfood_update_e2e: Simulates live upgrade from 0.1.1 to 0.1.2.

2.7 KiB Raw Blame History