Skip to content
alpha 0.1.0-alpha.7 is on crates.io. Install the CLI Start here

0012 - Update manifests

Status: Implemented (manifest format v2, signing, verification and CLI; runtime download/staging is spec 0013; deltas/rollout are spec 0028; platform apply is spec 0014/0025)

Phase 2 needs a signed description of a release artifact. This spec fixes the manifest format and its verification; the runtime is specified separately (0013 covers check/download/stage and 0014 the first apply path).

Scope

  • auro-update: manifest format v2, signing, verification, JSON encode/decode.
  • Artifact metadata: size and lowercase hex SHA-256.
  • Optional signed delta and rollout metadata (spec 0028).
  • auro manifest --artifact ... --key ... --out ... to produce a signed manifest.
  • Platform keys (<os>-<arch>) and publication timestamps as caller-supplied text.

Out of scope

  • Downloading, staging, applying or rolling back in this spec (the runtime is 0013 and 0014).
  • Delta application and rollout selection implementation details (spec 0028).
  • Channels, rollback execution, hosting behavior.
  • Hosting and CDN behavior.
  • Key distribution beyond the public key string; no built-in key pinning in this slice.
  • UI for update prompts.

Decisions

D1 - Format v2 is a flat JSON object with optional fields

{
  "format": 2,
  "version": "1.2.3",
  "platform": "linux-x86_64",
  "url": "https://example.test/app-1.2.3.tar.gz",
  "size": 42,
  "sha256": "...",
  "notes": "...",
  "published_at": "2026-11-17T12:00:00Z",
  "signature": "<base64 Ed25519 signature>"
}

delta and rollout are omitted when absent. Unknown fields are rejected. format other than 2 is an unsupported-format error, not a guess. Format v1 manifests are rejected by this build. sha256 is exactly 64 lowercase hexadecimal characters; verification rejects anything else before hashing an artifact.

D2 - Signature covers a canonical payload

The payload is the same fields without signature, serialized with serde_json in the struct's field order, including any present delta/rollout fields. The signature is Ed25519 over those bytes. A field reorder or rename is a format change; bump format and migrate. Manifest::verify checks format, presence of a signature, then the signature.

D3 - Artifact metadata is verified separately

Manifest::for_artifact reads the local file, records its byte length and SHA-256. Manifest::verify_artifact verifies the manifest signature first, then size and hash. A signed manifest for a different file fails.

D4 - CLI shape

auro generate-key --out release.key
auro manifest \
  --artifact target/release/bundle/app.tar.gz \
  --version 1.2.3 \
  --url https://example.test/app.tar.gz \
  --key release.key \
  --out latest.json \
  --notes "..." \
  --published-at 2026-11-17T12:00:00Z \
  [--platform linux-x86_64]

The platform defaults to <std::env::consts::OS>-<std::env::consts::ARCH>. The command prints the manifest path.

D5 - Trust, not installation

The signature and hash prevent a tampered manifest/artifact from being accepted. Spec 0013 downloads and stages a verified artifact; spec 0014 replaces a Linux AppImage and spec 0025 runs Windows installers or replaces a macOS .app. Package-manager apply remains separate, and nothing restarts or replaces a running app automatically.

Interfaces

#![allow(unused)]
fn main() {
pub struct Manifest {
    pub format: u32,
    pub version: String,
    pub platform: String,
    pub url: String,
    pub size: u64,
    pub sha256: String,
    pub notes: String,
    pub published_at: String,
    pub delta: Option<Delta>,
    pub rollout: Option<Rollout>,
    pub signature: String,
}

impl Manifest {
    pub fn new(...) -> Self;
    pub fn for_artifact(...) -> Result<Self, UpdateError>;
    pub fn with_delta(self, delta: Delta) -> Self;
    pub fn with_rollout(self, rollout: Rollout) -> Self;
    pub fn sign(self, key: &SigningKey) -> Result<Self, UpdateError>;
    pub fn verify(&self, key: &PublicKey) -> Result<(), UpdateError>;
    pub fn verify_artifact(&self, path: &Path, key: &PublicKey) -> Result<(), UpdateError>;
    pub fn to_json(&self) -> Result<String, UpdateError>;
    pub fn from_json(text: &str) -> Result<Self, UpdateError>;
}
}

Acceptance

  1. Signed manifest verifies; tampering with a field fails (signs_and_verifies_a_manifest, rejects_a_tampered_field).
  2. Empty signature, unknown format and malformed SHA-256 fail with the typed errors (rejects_an_empty_signature_and_unknown_format, rejects_a_malformed_artifact_hash).
  3. Artifact size/hash and manifest signature are both checked; a changed artifact fails (verifies_an_artifact_and_its_metadata).
  4. JSON round-trips byte-for-byte at the value level (json_round_trips).
  5. The CLI creates a manifest that verifies and describes the artifact (auro-cli release test).
  6. Delta/rollout metadata is signed and verified; see spec 0028.
  7. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Download/apply/staging/restart and rollbackUpdater runtime / AppImage / Windows and macOS / journal and restart
Deltas/patches and staged rollout percentagesBinary deltas and staged rollout
Key pinning and rotation inside the appTrust/update client spec
Update channels and UIPlatform/update UX follow-up
Hosting/CSP and mirror behaviorRelease service follow-up