TUF Update Generator

Manages The Update Framework (TUF) repository for secure over-the-air updates to Subgraph Citadel.

Core Roles

1. Repository Administrator (Root Authority): Manages the root of trust, creates channels, and authorizes delegates. See ADMINISTRATOR_GUIDE.md for full procedures.
2. Channel Owner (Delegate): Builds OS images and signs channel-specific metadata using a private key. See DELEGATE_GUIDE.md for a step-by-step setup guide.
3. Heartbeat Server (Standalone): Automatically synchronizes channels, aggregates updates into global snapshots, and refreshes timestamps to prevent repository expiry.

---

Configuration

The tool is designed to be resilient and runs both in the Citadel build tree and on standalone production servers.

1. Context Configuration

Configuration is loaded in the following priority:

1. Environment Variables: CITADEL_CLIENT, CITADEL_CHANNEL, UPDATE_SERVER.
2. Yocto Config: meta-citadel/conf/distro/citadel-distro.conf (if running in the build tree).

2. Secrets (Passphrases)

For automated/headless operation, passwords for private keys can be provided via environment variables:

• TUF_SNAPSHOT_PASSWORD
• TUF_TIMESTAMP_PASSWORD
• TUF_ROOT_IMAGE_PASSWORD
• TUF_KEY_PASSWORD (Generic fallback)

---

Channel Management Logic

The tool tracks repository state via repo/channels.json.

• Production Channels (stable, release, beta, alpha): Managed manually. The heartbeat server trusts the version numbers defined in channels.json.
• Dynamic Channels (all other names): The heartbeat server automatically fetches the latest metadata from the UPDATE_SERVER and updates channels.json if a new version is detected.

---

Common Workflows

Initialize a New Repository (Admin)

cargo run --admin init

Add a Channel Delegate (Admin)

Register a team member's public key to authorize them:

cargo run --admin add-delegate --name <channel> --public-key <path.pub>

Initialize a Channel (Delegate)

cargo run init-channel --name <channel>

Release Images (Delegate)

1. Build images: make installer
2. Add to metadata: cargo run add-images --channel <channel>
3. Publish: cargo run publish
4. Upload: cargo run upload

---

Command Reference

Command	Mode	Description
init	Admin	Initialize repo and generate all root-of-trust keys.
add-delegate	Admin	Register a delegate's public key in targets.json.
authorize-image-key	Admin	Sign a channel's image key with the Root Image Key.
init-channel	Delegate	Generate a new keypair and initial metadata for a channel.
generate-image-key	Delegate	Generate the image signing key used for OS builds.
add-images	Delegate	Add local .img files to a channel and sign.
publish	Delegate	Move staged metadata to the public repository directory.
upload	Utility	Push active channels and metadata to the update server.
install-keys	Utility	Export public/private keys to meta-citadel for OS building.
verify	Utility	Audit the local and remote repository integrity.
list	Utility	List all channels registered in the repository.

---

Security Notes

• Heartbeat Isolation: The heartbeat server only requires snapshot and timestamp keys. It never touches sensitive channel-signing keys.
• Atomic Permissions: The tool creates private key files with 0600 permissions atomically to prevent race conditions.
• Integrity: The heartbeat server verifies remote channel versions to prevent metadata rollbacks.

See scripts/INSTALL.md for production deployment instructions.