Crate aegis_wire_formats

Expand description

§aegis-wire-formats

Signed attestation manifest format for aegis-boot USB sticks. Defines the on-disk ::/aegis-boot-manifest.json shape the flash-time attestation writes and that runtime verifiers (rescue-tui, aegis-boot doctor --stick, aegis-hwsim E6 attestation-roundtrip) read back.

Part of the aegis-boot rescue environment — a signed-chain UEFI Secure Boot stick that boots any ISO.

§Scope

This crate ships:

Serde types for the manifest envelope (Manifest, Device, EspPartition, DataPartition, EspFileEntry, PcrEntry).
Schema version constant pinning the wire-format version at 1 (locked by #277).
Optional JSON Schema generation behind the schema feature — enables #[derive(JsonSchema)] on every public type and compiles the aegis-wire-formats-schema-docgen binary that writes aegis-boot-manifest.schema.json consumers can validate against.

Deliberately not shipped here:

Writer / signer / filesystem I/O code — that logic is tightly coupled to the direct_install flow on Linux and lives in the aegis-cli crate.
minisign signature verification — callers receive the manifest body + a detached signature and verify out-of-band.

§Feature flags

schema (off by default) — pulls schemars in, adds JsonSchema derives, enables the aegis-wire-formats-schema-docgen binary used by the parent workspace’s CI drift-check.

§Platform support

Pure Rust, no platform-specific code. Works anywhere serde + serde_json work.

§Status

Pre-1.0. Schema version is locked at 1; API may still gain minor conveniences before a crates.io publish. Consume via the aegis-boot workspace.

§License

Licensed under either of Apache-2.0 or MIT at your option.

§Rust API

The core type is Manifest — the on-disk JSON body that gets written to ::/aegis-boot-manifest.json + signed into ::/aegis-boot-manifest.json.minisig. Every field is part of a pinned wire contract; see the comments on each struct for the invariants a verifier must enforce.

§Schema versioning

SCHEMA_VERSION is the canonical value for schema_version. Bump it only alongside a shape-breaking change (removing a field, changing a field’s type). Adding a new optional field is backwards-compatible and does not require a version bump — the verifier ignores fields it doesn’t know about.

§JSON Schema

With the schema feature enabled, every public type derives schemars::JsonSchema. The aegis-wire-formats-schema-docgen binary emits a validated JSON Schema document to docs/reference/schemas/aegis-boot-manifest.schema.json in the parent workspace; third-party verifiers can pin to this schema.

§Two wire formats under one crate

This crate hosts two logically distinct JSON wire formats that both carry aegis-boot provenance:

On-ESP manifest (Manifest, SCHEMA_VERSION) — signed record written into ::/aegis-boot-manifest.json at flash time, read by runtime verifiers. Phase 4a of #286.
Host attestation receipt (Attestation, ATTESTATION_SCHEMA_VERSION) — per-flash audit record written to $XDG_DATA_HOME/aegis-boot/attestations/ for chain-of-custody + fleet inventory. Phase 4c-1 of #286.
CLI envelopes (Version, ListReport, AttestListReport, VerifyReport, UpdateReport, RecommendReport, CompatReport, CompatSubmitReport, DoctorReport, with their *_SCHEMA_VERSION constants) — the --json envelopes emitted by aegis-boot --version --json, ... list --json, ... attest list --json, ... verify --json, ... update --json, ... recommend --json, ... compat --json, ... compat --submit --json, and siblings. Phase 4b of #286.

Each contract is independently versioned — a change to one schema does not require bumping the others. They are co-located in the same crate because they are all “aegis-boot wire-format structs for third-party consumers” and sharing the optional schema feature + docgen infrastructure is cheaper than forking it across N crates. A future crate rename (aegis-wire-formats or similar) may follow once the full CLI envelope set lands.

Structs§

AttestListError: Parse-failure entry inside an AttestListReport. Consumer decision: show the operator which file failed + why, so they can audit / repair / delete.
AttestListReport: Envelope emitted by aegis-boot attest list --json. Scans the host’s attestation directory, attempts to parse each file, and reports either a parsed summary or a parse-error placeholder per entry. Enables monitoring / fleet tools to audit chain-of-custody across all flashed sticks on a host.
AttestListSuccess: Successfully-parsed attestation summary inside an AttestListReport. Deliberately a strict subset of the full Attestation — enough to drive a dashboard without requiring consumers to re-parse each file. Full detail is one aegis-boot attest show <path> away.
Attestation: One flash + zero-or-more ISO additions, captured as a single JSON document on the host. Stored under $XDG_DATA_HOME/aegis-boot/attestations/ (or ~/.local/share/aegis-boot/attestations/ if XDG_DATA_HOME is unset). The aegis-boot attest list / attest show commands read these back for chain-of-custody queries.
CliError: Generic error envelope emitted when a subcommand fails before it can produce its subcommand-specific --json envelope. Examples: aegis-boot list --json before mount-resolution succeeds; aegis-boot verify --json before a stick is found.
CompatCatalogReport: Full-catalog variant of CompatReport.
CompatEntry: One hardware-compatibility DB row. Mirrors docs/HARDWARE_COMPAT.md; every entry corresponds to a real operator report (or the QEMU reference environment).
CompatMissReport: Miss variant of CompatReport — the query was well-formed but didn’t match any DB entry. Carries report_url so the operator can file a new entry; deliberately omits tool_version to match the existing wire format.
CompatMyMachineMissReport: My-machine-miss variant of CompatReport — --my-machine or --submit couldn’t auto-fill the query from DMI. Minimal envelope (just schema_version + error) to match the existing wire format.
CompatSingleReport: Single-entry variant of CompatReport.
CompatSubmitReport: Envelope emitted by aegis-boot compat --submit --json — the draft-a-hardware-report flow. Collects DMI identity + builds a pre-filled GitHub issue URL the operator can open to file a report. Independent schema from CompatReport because the consumer contracts diverge: lookup drives scripted decisions, submit drives an operator workflow.
DataPartition: Identity of the AEGIS_ISOS data partition (partition 2).
Device: Device identity captured at flash time. All values come from the freshly-written GPT (blkid + sgdisk -p); the verifier re-reads them at runtime and asserts equality.
DoctorReport: Envelope emitted by aegis-boot doctor --json. Reports host + stick health as a rollup score + per-check rows. The monitoring / CI consumer target — a non-zero has_any_fail is the signal to surface to an operator.
DoctorRow: One check result in a DoctorReport.
EspFileEntry: A single file on the ESP with its content hash and size.
EspPartition: Identity of the ESP partition (partition 1).
FailureMicroreport: Tier-A anonymous failure microreport — written by rescue-tui / initramfs to AEGIS_ISOS/aegis-boot-logs/<ts>-<hash>.json when a classifiable boot failure occurs, so the operator can later include the log in an aegis-boot bug-report bundle (#342 Phase 2).
HostInfo: Host environment fingerprint at flash time.
IsoRecord: One aegis-boot add operation appended to the stick’s attestation record.
ListAttestationSummary: Compact attestation summary embedded in ListReport. Derived from the stored Attestation record; smaller than the full attestation (no device fingerprint, no host kernel string) so the list envelope stays lightweight.
ListIsoSummary: Per-ISO detail in ListReport. The display_name + description fields come from an optional <iso>.aegis.toml operator-label sidecar (#246); they are always present in the wire format (as null when absent) so consumers see a stable shape.
ListReport: Envelope emitted by aegis-boot list --json. Reports the ISOs discovered on a stick’s AEGIS_ISOS data partition, plus the attestation summary if one was recorded at flash time.
Manifest: Top-level manifest body. Serialized field order matches the declaration order below — relied on for canonical JSON stability (the signature is computed over serde_json::to_vec(&Manifest)).
PcrEntry: Expected TPM PCR value at an aegis-boot stick’s first post-boot measurement. Empty in PR3; populated once E6 locks the PCR selection.
RecommendCatalogReport: Full-catalog variant of RecommendReport.
RecommendEntry: One curated catalog entry. Used in both RecommendCatalogReport::entries and RecommendSingleReport::entry.
RecommendMissReport: Miss variant of RecommendReport — no catalog entry matched the given slug. The envelope is deliberately asymmetric from the success variants (no tool_version) to match the existing wire format; tightening to always emit tool_version would be an additive (non-breaking) future change.
RecommendSingleReport: Single-entry variant of RecommendReport.
TargetInfo: Target stick fingerprint at flash time.
UpdateChainEntry: One signed-chain entry in an UpdateEligibility::Eligible response. Two mutually-exclusive wire shapes via untagged-enum dispatch on the presence of sha256 vs error.
UpdateFileDiff: Per-file diff row between what’s currently on the stick’s ESP and what a fresh mkusb / direct-install flash would write. One row per canonical ESP destination (see direct_install::ESP_DEST_*).
UpdateReport: Envelope emitted by aegis-boot update --json. Phase 1 of #181 is eligibility-check-only: answers “would a non-destructive signed-chain rotation apply cleanly to this stick?” — the actual rotation is Phase 2. The envelope’s outer fields (schema_version, tool_version, device) are common; the [eligibility] flattened enum carries the variant-specific body.
VerifyEntry: One ISO’s verdict inside a VerifyReport. The verdict field is the discriminator; variant-specific fields follow via #[serde(flatten)]. Consumer contract: branch on verdict, expect the fields documented for that variant.
VerifyReport: Envelope emitted by aegis-boot verify --json. Re-verifies every ISO on a stick against its sidecar checksum and reports a per-ISO verdict plus a summary tally. Used by CI / monitoring to audit that a stick’s ISOs haven’t bit-rotted, been replaced, or lost their sha256 sidecars.
VerifySummary: Tally of per-ISO verdicts in a VerifyReport. any_failure is the summary bit downstream tooling (CI, dashboards) branches on.
Version: Envelope emitted by aegis-boot --version --json. Lets scripted consumers (install-one-liner assertions, Homebrew formula tests, ansible-verified installs) parse the version without regex on the human-readable string.

Enums§

AttestListEntry: One entry in an AttestListReport. Two mutually-exclusive wire shapes via serde’s untagged tagging:
CompatReport: Envelope emitted by aegis-boot compat --json. Untagged wrapper around 4 mutually-exclusive shapes: full catalog, single match, miss (query matched no DB entry), or my-machine-miss (DMI lookup couldn’t resolve an identity).
RecommendReport: Envelope emitted by aegis-boot recommend --json. Untagged wrapper around three mutually-exclusive shapes: a full catalog listing, a single-entry response, or a miss. Consumers branch on the presence of entries / entry / error.
UpdateChainResult: Per-chain-entry result. Untagged to match the current wire format’s mutually-exclusive shape (no discriminator tag — the consumer branches on the presence of sha256 vs error).
UpdateEligibility: Outcome of the eligibility check. Internally-tagged under eligibility with the tag values "ELIGIBLE" and "INELIGIBLE" (upper-case to match the existing wire format). flatten-combined with UpdateReport’s outer fields so the emitted JSON preserves the schema_version, tool_version, device, eligibility, … ordering consumers parse against.
VerifyVerdict: Per-ISO verdict variants. Internally-tagged under verdict; a consumer that doesn’t recognize a future variant can fall back on the tag string.

Constants§

ATTESTATION_SCHEMA_VERSION: Locked schema version for the host-side Attestation record. Independent of SCHEMA_VERSION — either contract can advance without the other.
ATTEST_LIST_SCHEMA_VERSION: Locked schema version for the AttestListReport envelope emitted by aegis-boot attest list --json. Independent of the other envelope contracts.
CLI_ERROR_SCHEMA_VERSION: Locked schema version for the CliError envelope — the generic {schema_version, error} shape emitted by any subcommand that fails before it can produce its subcommand-specific --json envelope. Shared by multiple subcommands because the pre-dispatch error path is identical across them.
COMPAT_SCHEMA_VERSION: Locked schema version for the CompatReport envelope emitted by aegis-boot compat --json. Shared by the 4 mutually-exclusive shapes (catalog / single / miss / my-machine-miss). Independent of the other envelope contracts.
COMPAT_SUBMIT_SCHEMA_VERSION: Locked schema version for the CompatSubmitReport envelope emitted by aegis-boot compat --submit --json — the draft-a-hardware-report flow. Deliberately a separate schema from CompatReport because the two surfaces have different consumer contracts (operators draft-submit vs. scripted lookup).
DOCTOR_SCHEMA_VERSION: Locked schema version for the DoctorReport envelope emitted by aegis-boot doctor --json. Independent of the other envelope contracts.
FAILURE_MICROREPORT_SCHEMA_VERSION: Locked schema version for the FailureMicroreport envelope — the Tier-A anonymous on-stick failure log written by rescue-tui / initramfs when a classifiable boot failure occurs. Per #342 Phase 2. Anonymous-by-construction: no hostname, no DMI serial, no free-form error text; just vendor_family + bios_year + classified error code + an opaque hash of the full error text.
LIST_SCHEMA_VERSION: Locked schema version for the ListReport envelope emitted by aegis-boot list --json. Independent of the other envelope contracts.
RECOMMEND_SCHEMA_VERSION: Locked schema version for the RecommendReport envelope emitted by aegis-boot recommend --json. Independent of the other envelope contracts.
SCHEMA_VERSION: Locked schema version for the on-ESP signed Manifest. Bump alongside a breaking shape change (removing a field, changing a field’s type). Adding a new optional field is backwards-compatible and does not require a version bump — the verifier ignores fields it doesn’t know about.
UPDATE_SCHEMA_VERSION: Locked schema version for the UpdateReport envelope emitted by aegis-boot update --json. Independent of the other envelope contracts.
VERIFY_SCHEMA_VERSION: Locked schema version for the VerifyReport envelope emitted by aegis-boot verify --json. Independent of the other envelope contracts.
VERSION_SCHEMA_VERSION: Locked schema version for the Version envelope emitted by aegis-boot --version --json. Independent of the manifest and attestation contract versions.