From cc5c93596d0864c526b69a4f7efca805599b6ea1 Mon Sep 17 00:00:00 2001 From: Kevin Janssen Date: Sat, 14 Nov 2026 15:55:45 +0100 Subject: [PATCH] feat: add pure signed agent release verifier without apply authority --- Cargo.lock | 13 + Cargo.toml | 2 +- crates/updater/Cargo.toml | 14 + crates/updater/src/lib.rs | 12 + crates/updater/src/manifest.rs | 385 +++++++++++++++ crates/updater/tests/fixtures/release_v1.json | 1 + crates/updater/tests/release_contract.rs | 317 +++++++++++++ docs/agent-updater-proposal.md | 442 ++++++++++++++++++ 8 files changed, 1185 insertions(+), 1 deletion(-) create mode 100644 crates/updater/Cargo.toml create mode 100644 crates/updater/src/lib.rs create mode 100644 crates/updater/src/manifest.rs create mode 100644 crates/updater/tests/fixtures/release_v1.json create mode 100644 crates/updater/tests/release_contract.rs create mode 100644 docs/agent-updater-proposal.md diff --git a/Cargo.lock b/Cargo.lock index 08bd7ff..2a283d4 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2364,6 +2364,19 @@ dependencies = [ "uuid", ] +[[package]] +name = "rmm-updater" +version = "0.1.0" +dependencies = [ + "anyhow", + "ed25519-dalek", + "hex", + "serde", + "serde_json", + "sha2 0.10.9", + "uuid", +] + [[package]] name = "rsa" version = "0.9.10" diff --git a/Cargo.toml b/Cargo.toml index ffa935a..1101ac5 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,7 @@ [workspace] resolver = "2" exclude = ["crates/oidc-auth"] -members = ["crates/domain", "crates/protocol", "crates/persistence", "crates/server", "crates/agent-linux", "crates/agent-core", "crates/agent-windows", "crates/agent", "crates/privileged-helper"] +members = ["crates/domain", "crates/protocol", "crates/persistence", "crates/server", "crates/agent-linux", "crates/agent-core", "crates/agent-windows", "crates/agent", "crates/privileged-helper", "crates/updater"] [workspace.package] version = "0.1.0" diff --git a/crates/updater/Cargo.toml b/crates/updater/Cargo.toml new file mode 100644 index 0000000..ed2c5b9 --- /dev/null +++ b/crates/updater/Cargo.toml @@ -0,0 +1,14 @@ +[package] +name = "rmm-updater" +version.workspace = true +edition.workspace = true +license.workspace = true + +[dependencies] +anyhow.workspace = true +ed25519-dalek = "=2.2.0" +hex.workspace = true +serde.workspace = true +serde_json.workspace = true +sha2.workspace = true +uuid.workspace = true diff --git a/crates/updater/src/lib.rs b/crates/updater/src/lib.rs new file mode 100644 index 0000000..385637f --- /dev/null +++ b/crates/updater/src/lib.rs @@ -0,0 +1,12 @@ +//! Pure release verification. This crate does not install, stage, start services, +//! grant approval, persist antirollback state, or trust keys from the network. +//! +//! See docs/agent-updater-proposal.md for the separate, unfinished integration. + +mod manifest; + +pub use manifest::{ + ActiveRelease, ArtifactDescriptor, ArtifactRole, MAX_ARTIFACT_BYTES, MAX_MANIFEST_BYTES, + Platform, RELEASE_SIGNATURE_DOMAIN, ReleaseManifest, ReleaseRelation, SignedRelease, + TrustedContext, TrustedUpdateKey, UpdateKeyring, VerifiedRelease, verify_release, +}; diff --git a/crates/updater/src/manifest.rs b/crates/updater/src/manifest.rs new file mode 100644 index 0000000..df5ba57 --- /dev/null +++ b/crates/updater/src/manifest.rs @@ -0,0 +1,385 @@ +use std::{collections::BTreeMap, io::Read}; + +use anyhow::{Context, Result, bail, ensure}; +use ed25519_dalek::{Signature, VerifyingKey}; +use serde::{Deserialize, Serialize}; +use sha2::{Digest, Sha256}; +use uuid::Uuid; + +pub const MAX_MANIFEST_BYTES: usize = 16 * 1024; +/// Verification limit for a FUTURE update-specific streaming transport. +/// The existing server artifact route only permits 256 KiB and is unchanged. +pub const MAX_ARTIFACT_BYTES: u64 = 256 * 1024 * 1024; +pub const RELEASE_SIGNATURE_DOMAIN: &[u8] = b"rmm.agent-release.v1\0"; + +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub enum Platform { + #[serde(rename = "x86_64-unknown-linux-gnu")] + LinuxX64, + #[serde(rename = "x86_64-pc-windows-msvc")] + WindowsX64, +} + +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum ArtifactRole { + Agent, + Helper, +} + +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct ArtifactDescriptor { + pub role: ArtifactRole, + pub artifact_id: Uuid, + pub sha256: String, + pub bytes: u64, +} + +/// Exact field order defines codec version 1; no maps or floating point fields. +/// These public types describe UNTRUSTED metadata, never update authority. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct ReleaseManifest { + pub schema_version: u32, + pub release_id: Uuid, + pub release_sequence: u64, + pub version: String, + pub platform: Platform, + pub published_at: u64, + pub expires_at: u64, + pub protocol_major: u32, + pub state_schema: u32, + pub minimum_updater_version: u32, + pub artifacts: [ArtifactDescriptor; 2], +} + +/// Already-decoded, bounded transport input. No algorithm negotiation exists. +pub struct SignedRelease<'a> { + pub schema_version: u32, + pub key_id: &'a str, + pub payload_bytes: &'a [u8], + pub signature: &'a [u8], +} + +/// Provisioned update trust, not a key returned by a manifest/job/server request. +/// Construction validates raw keys and IDs; it does not authenticate provisioning. +pub struct TrustedUpdateKey { + key: VerifyingKey, + key_id: String, + platform: Platform, + first_sequence: u64, + last_sequence: u64, + revoked: bool, +} + +impl TrustedUpdateKey { + pub fn new( + public_key: [u8; 32], + platform: Platform, + first_sequence: u64, + last_sequence: u64, + revoked: bool, + ) -> Result { + let key = VerifyingKey::from_bytes(&public_key).context("invalid update public key")?; + ensure!(!key.is_weak(), "weak update public key"); + ensure!( + first_sequence > 0 && last_sequence >= first_sequence, + "invalid key sequence range" + ); + Ok(Self { + key, + key_id: digest(&public_key), + platform, + first_sequence, + last_sequence, + revoked, + }) + } + + pub fn key_id(&self) -> &str { + &self.key_id + } +} + +pub struct UpdateKeyring { + generation: u64, + keys: BTreeMap, +} + +impl UpdateKeyring { + pub fn new(generation: u64, keys: Vec) -> Result { + ensure!( + generation > 0 && !keys.is_empty() && keys.len() <= 16, + "invalid provisioned keyring" + ); + let mut indexed = BTreeMap::new(); + for key in keys { + ensure!(!indexed.contains_key(key.key_id()), "duplicate update key"); + indexed.insert(key.key_id.clone(), key); + } + Ok(Self { + generation, + keys: indexed, + }) + } +} + +#[derive(Clone, Debug)] +pub struct ActiveRelease { + pub sequence: u64, + pub manifest_sha256: String, +} + +/// Must be obtained from authenticated local state and a trusted clock. +/// No boolean `approved`/`ready` is accepted or produced here. Persistence, +/// rollback detection and independent sync remain the caller's responsibility. +pub struct TrustedContext { + pub platform: Platform, + pub now_utc_seconds: u64, + pub keyring_generation: u64, + pub protocol_major: u32, + pub state_schema: u32, + pub updater_version: u32, + pub minimum_release_sequence: u64, + pub active_release: Option, +} + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum ReleaseRelation { + AboveActivationFloor, + /// Metadata identity only: neither actual binary health nor a job Noop proof. + SameActiveManifest, +} + +/// Private construction proves only release metadata validity at verification. +/// Holding this value grants NO permission to download, stop, install or start. +pub struct VerifiedRelease { + manifest: ReleaseManifest, + manifest_sha256: String, + key_id: String, + keyring_generation: u64, + relation: ReleaseRelation, +} + +impl VerifiedRelease { + pub fn manifest(&self) -> &ReleaseManifest { + &self.manifest + } + + pub fn manifest_sha256(&self) -> &str { + &self.manifest_sha256 + } + + pub fn key_id(&self) -> &str { + &self.key_id + } + + pub fn keyring_generation(&self) -> u64 { + self.keyring_generation + } + + pub fn relation(&self) -> ReleaseRelation { + self.relation + } + + /// Verify a complete reader with a fixed 32 KiB buffer and no file writes. + /// A caller supplying a socket/pipe must enforce its own timeout and permit. + /// Descriptors come only from this verified release, never caller input. + pub fn verify_artifact(&self, role: ArtifactRole, mut reader: impl Read) -> Result<()> { + let descriptor = match role { + ArtifactRole::Agent => &self.manifest.artifacts[0], + ArtifactRole::Helper => &self.manifest.artifacts[1], + }; + let mut buffer = [0_u8; 32 * 1024]; + let mut remaining = descriptor.bytes; + let mut hasher = Sha256::new(); + while remaining > 0 { + let limit = remaining.min(buffer.len() as u64) as usize; + let size = match reader.read(&mut buffer[..limit]) { + Ok(size) => size, + Err(error) if error.kind() == std::io::ErrorKind::Interrupted => continue, + Err(error) => return Err(error).context("release artifact read failed"), + }; + ensure!(size > 0, "release artifact truncated"); + hasher.update(&buffer[..size]); + remaining -= size as u64; + } + loop { + match reader.read(&mut buffer[..1]) { + Ok(0) => break, + Ok(_) => bail!("release artifact has extra bytes"), + Err(error) if error.kind() == std::io::ErrorKind::Interrupted => continue, + Err(error) => return Err(error).context("release artifact EOF check failed"), + } + } + ensure!( + hex::encode(hasher.finalize()) == descriptor.sha256, + "release artifact hash mismatch" + ); + Ok(()) + } +} + +pub fn verify_release( + signed: SignedRelease<'_>, + keyring: &UpdateKeyring, + context: &TrustedContext, +) -> Result { + ensure!( + signed.schema_version == 1, + "unsupported release envelope schema" + ); + ensure!( + !signed.payload_bytes.is_empty() && signed.payload_bytes.len() <= MAX_MANIFEST_BYTES, + "release manifest size limit" + ); + ensure!(is_digest(signed.key_id), "invalid update key ID"); + ensure!( + keyring.generation == context.keyring_generation, + "update trust generation mismatch" + ); + let key = keyring + .keys + .get(signed.key_id) + .context("untrusted update key")?; + ensure!( + !key.revoked && key.platform == context.platform, + "update key revoked or wrong platform" + ); + let signature = + Signature::from_slice(signed.signature).context("invalid release signature size")?; + let mut message = + Vec::with_capacity(RELEASE_SIGNATURE_DOMAIN.len() + signed.payload_bytes.len()); + message.extend_from_slice(RELEASE_SIGNATURE_DOMAIN); + message.extend_from_slice(signed.payload_bytes); + key.key + .verify_strict(&message, &signature) + .context("release signature rejected")?; + + let manifest: ReleaseManifest = + serde_json::from_slice(signed.payload_bytes).context("invalid release manifest schema")?; + ensure!( + serde_json::to_vec(&manifest)? == signed.payload_bytes, + "noncanonical release manifest" + ); + validate_manifest(&manifest, context)?; + ensure!( + (key.first_sequence..=key.last_sequence).contains(&manifest.release_sequence), + "release outside update key sequence range" + ); + let manifest_sha256 = digest(signed.payload_bytes); + let relation = match &context.active_release { + Some(active) => { + ensure!( + active.sequence > 0 + && is_digest(&active.manifest_sha256) + && active.sequence <= context.minimum_release_sequence, + "invalid trusted active release state" + ); + if manifest.release_sequence == active.sequence { + ensure!( + manifest_sha256 == active.manifest_sha256, + "release sequence content conflict" + ); + ReleaseRelation::SameActiveManifest + } else { + ensure!( + manifest.release_sequence > context.minimum_release_sequence, + "release is not above activation floor" + ); + ReleaseRelation::AboveActivationFloor + } + } + None => { + ensure!( + manifest.release_sequence > context.minimum_release_sequence, + "release is not above activation floor" + ); + ReleaseRelation::AboveActivationFloor + } + }; + Ok(VerifiedRelease { + manifest, + manifest_sha256, + key_id: signed.key_id.to_owned(), + keyring_generation: keyring.generation, + relation, + }) +} + +fn validate_manifest(manifest: &ReleaseManifest, context: &TrustedContext) -> Result<()> { + ensure!( + manifest.schema_version == 1, + "unsupported release manifest schema" + ); + ensure!( + !manifest.release_id.is_nil() && manifest.release_sequence > 0, + "invalid release identity" + ); + ensure!( + !manifest.version.is_empty() + && manifest.version.len() <= 64 + && manifest + .version + .bytes() + .all(|byte| byte.is_ascii_alphanumeric() || b".-+_".contains(&byte)), + "invalid release version label" + ); + ensure!( + manifest.platform == context.platform, + "release platform mismatch" + ); + ensure!( + manifest.published_at <= context.now_utc_seconds + && manifest.expires_at > context.now_utc_seconds + && manifest.expires_at > manifest.published_at, + "release outside trusted validity interval" + ); + ensure!( + context.protocol_major > 0 && manifest.protocol_major == context.protocol_major, + "incompatible release protocol" + ); + ensure!( + context.state_schema > 0 && manifest.state_schema == context.state_schema, + "incompatible release state schema" + ); + ensure!( + manifest.minimum_updater_version > 0 + && manifest.minimum_updater_version <= context.updater_version, + "updater version unsupported" + ); + ensure!( + manifest.release_sequence >= context.minimum_release_sequence, + "release below activation floor" + ); + ensure!( + manifest.artifacts[0].role == ArtifactRole::Agent + && manifest.artifacts[1].role == ArtifactRole::Helper, + "release requires ordered agent and helper artifacts" + ); + ensure!( + manifest.artifacts[0].artifact_id != manifest.artifacts[1].artifact_id, + "duplicate release artifact ID" + ); + for artifact in &manifest.artifacts { + ensure!( + !artifact.artifact_id.is_nil() + && is_digest(&artifact.sha256) + && (1..=MAX_ARTIFACT_BYTES).contains(&artifact.bytes), + "invalid release artifact descriptor" + ); + } + Ok(()) +} + +fn digest(bytes: &[u8]) -> String { + hex::encode(Sha256::digest(bytes)) +} + +fn is_digest(value: &str) -> bool { + value.len() == 64 + && value + .bytes() + .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte)) +} diff --git a/crates/updater/tests/fixtures/release_v1.json b/crates/updater/tests/fixtures/release_v1.json new file mode 100644 index 0000000..052ee18 --- /dev/null +++ b/crates/updater/tests/fixtures/release_v1.json @@ -0,0 +1 @@ +{"schema_version":1,"release_id":"00000000-0000-0000-0000-000000000001","release_sequence":4,"version":"0.2.0","platform":"x86_64-unknown-linux-gnu","published_at":90,"expires_at":110,"protocol_major":1,"state_schema":1,"minimum_updater_version":1,"artifacts":[{"role":"agent","artifact_id":"00000000-0000-0000-0000-000000000002","sha256":"8a24d82ccecfb6de46d0fd3488549b3c6757a4c05aab0a4b15c1b73e47000dbc","bytes":11},{"role":"helper","artifact_id":"00000000-0000-0000-0000-000000000003","sha256":"dd4e40b8a4de19a3b9143d926178927aea04ba0316f44f7fde254ecd51931d22","bytes":12}]} \ No newline at end of file diff --git a/crates/updater/tests/release_contract.rs b/crates/updater/tests/release_contract.rs new file mode 100644 index 0000000..97356ce --- /dev/null +++ b/crates/updater/tests/release_contract.rs @@ -0,0 +1,317 @@ +use std::io::{self, Cursor, Read}; + +use ed25519_dalek::{Signer, SigningKey}; +use rmm_updater::*; +use sha2::{Digest, Sha256}; +use uuid::Uuid; + +fn hash(bytes: &[u8]) -> String { + hex::encode(Sha256::digest(bytes)) +} + +fn key(revoked: bool, first: u64, last: u64) -> TrustedUpdateKey { + TrustedUpdateKey::new( + SigningKey::from_bytes(&[41; 32]).verifying_key().to_bytes(), + Platform::LinuxX64, + first, + last, + revoked, + ) + .unwrap() +} + +fn context() -> TrustedContext { + TrustedContext { + platform: Platform::LinuxX64, + now_utc_seconds: 100, + keyring_generation: 7, + protocol_major: 1, + state_schema: 1, + updater_version: 1, + minimum_release_sequence: 3, + active_release: Some(ActiveRelease { + sequence: 3, + manifest_sha256: hash(b"previous immutable manifest"), + }), + } +} + +fn manifest() -> ReleaseManifest { + ReleaseManifest { + schema_version: 1, + release_id: Uuid::from_u128(1), + release_sequence: 4, + version: "0.2.0".into(), + platform: Platform::LinuxX64, + published_at: 90, + expires_at: 110, + protocol_major: 1, + state_schema: 1, + minimum_updater_version: 1, + artifacts: [ + ArtifactDescriptor { + role: ArtifactRole::Agent, + artifact_id: Uuid::from_u128(2), + sha256: hash(b"agent image"), + bytes: 11, + }, + ArtifactDescriptor { + role: ArtifactRole::Helper, + artifact_id: Uuid::from_u128(3), + sha256: hash(b"helper image"), + bytes: 12, + }, + ], + } +} + +fn verify_bytes(payload: &[u8], context: &TrustedContext) -> anyhow::Result { + let signer = SigningKey::from_bytes(&[41; 32]); + let mut message = RELEASE_SIGNATURE_DOMAIN.to_vec(); + message.extend_from_slice(payload); + let signature = signer.sign(&message).to_bytes(); + let pinned = key(false, 1, 20); + let key_id = pinned.key_id().to_owned(); + verify_release( + SignedRelease { + schema_version: 1, + key_id: &key_id, + payload_bytes: payload, + signature: &signature, + }, + &UpdateKeyring::new(7, vec![pinned]).unwrap(), + context, + ) +} + +fn verify(manifest: &ReleaseManifest, context: &TrustedContext) -> anyhow::Result { + verify_bytes(&serde_json::to_vec(manifest).unwrap(), context) +} + +#[test] +fn canonical_release_and_exact_role_bytes_are_metadata_only() { + let payload = serde_json::to_vec(&manifest()).unwrap(); + assert_eq!(payload, include_bytes!("fixtures/release_v1.json")); + let checked = verify_bytes(&payload, &context()).unwrap(); + assert_eq!(checked.manifest_sha256(), hash(&payload)); + assert_eq!(checked.keyring_generation(), 7); + assert_eq!(checked.key_id(), key(false, 1, 20).key_id()); + assert_eq!(checked.manifest().release_sequence, 4); + assert_eq!(checked.relation(), ReleaseRelation::AboveActivationFloor); + checked + .verify_artifact(ArtifactRole::Agent, Cursor::new(b"agent image")) + .unwrap(); + checked + .verify_artifact(ArtifactRole::Helper, Cursor::new(b"helper image")) + .unwrap(); + assert!( + checked + .verify_artifact(ArtifactRole::Agent, Cursor::new(b"helper image")) + .is_err() + ); +} + +#[test] +fn signature_domain_bytes_unknown_key_and_revocation_are_independent() { + let payload = serde_json::to_vec(&manifest()).unwrap(); + let signer = SigningKey::from_bytes(&[41; 32]); + let mut message = RELEASE_SIGNATURE_DOMAIN.to_vec(); + message.extend_from_slice(&payload); + let signature = signer.sign(&message).to_bytes(); + let pinned = key(false, 1, 20); + let key_id = pinned.key_id().to_owned(); + let run = |bytes: &[u8], signature: &[u8], id: &str, revoked, first, last| { + verify_release( + SignedRelease { + schema_version: 1, + key_id: id, + payload_bytes: bytes, + signature, + }, + &UpdateKeyring::new(7, vec![key(revoked, first, last)]).unwrap(), + &context(), + ) + }; + assert!(run(&payload, &signature, &key_id, false, 1, 20).is_ok()); + let mut changed = payload.clone(); + changed[0] = b'['; + assert!(run(&changed, &signature, &key_id, false, 1, 20).is_err()); + assert!( + run( + &payload, + &signer.sign(&payload).to_bytes(), + &key_id, + false, + 1, + 20 + ) + .is_err() + ); + let foreign = SigningKey::from_bytes(&[42; 32]).sign(&message).to_bytes(); + assert!(run(&payload, &foreign, &key_id, false, 1, 20).is_err()); + assert!(run(&payload, &signature[..63], &key_id, false, 1, 20).is_err()); + assert!(run(&payload, &signature, &hash(b"job key"), false, 1, 20).is_err()); + assert!(run(&payload, &signature, &key_id, true, 1, 20).is_err()); + assert!(run(&payload, &signature, &key_id, false, 5, 20).is_err()); + assert!(run(&payload, &signature, &key_id, false, 1, 3).is_err()); +} + +#[test] +fn signed_noncanonical_unknown_duplicate_and_oversize_payloads_are_rejected() { + let payload = String::from_utf8(serde_json::to_vec(&manifest()).unwrap()).unwrap(); + for changed in [ + format!(" {payload}"), + payload.replacen(":1,", ": 1,", 1), + payload.replacen("{", "{\"untrusted\":true,", 1), + payload.replacen("{", "{\"schema_version\":1,", 1), + payload.replacen("\"bytes\":11", "\"bytes\":11,\"path\":\"/etc/passwd\"", 1), + payload.replacen("\"release_sequence\":4", "\"release_sequence\":4.0", 1), + payload.replacen("x86_64-unknown-linux-gnu", "aarch64-unknown-linux-gnu", 1), + ] { + assert!(verify_bytes(changed.as_bytes(), &context()).is_err()); + } + assert!(verify_bytes(&vec![b' '; MAX_MANIFEST_BYTES + 1], &context()).is_err()); + assert!(verify_bytes(b"", &context()).is_err()); +} + +#[test] +fn incompatible_clock_platform_state_protocol_and_trust_contexts_are_rejected() { + let mut ctx = context(); + ctx.keyring_generation = 6; + assert!(verify(&manifest(), &ctx).is_err()); + ctx = context(); + ctx.platform = Platform::WindowsX64; + assert!(verify(&manifest(), &ctx).is_err()); + for now in [89, 110, 111] { + ctx = context(); + ctx.now_utc_seconds = now; + assert!(verify(&manifest(), &ctx).is_err()); + } + let changes: [fn(&mut ReleaseManifest); 7] = [ + |m| m.schema_version = 2, + |m| m.platform = Platform::WindowsX64, + |m| m.protocol_major = 2, + |m| m.state_schema = 2, + |m| m.minimum_updater_version = 2, + |m| m.minimum_updater_version = 0, + |m| m.published_at = m.expires_at, + ]; + for change in changes { + let mut m = manifest(); + change(&mut m); + assert!(verify(&m, &context()).is_err()); + } +} + +#[test] +fn monotone_floor_same_sequence_conflict_and_postrollback_state_are_preserved() { + let mut ctx = context(); + let mut m = manifest(); + m.release_sequence = 2; + assert!(verify(&m, &ctx).is_err()); + m.release_sequence = 3; + assert!(verify(&m, &ctx).is_err()); + ctx.active_release.as_mut().unwrap().manifest_sha256 = hash(&serde_json::to_vec(&m).unwrap()); + assert_eq!( + verify(&m, &ctx).unwrap().relation(), + ReleaseRelation::SameActiveManifest + ); + m.version = "modified same sequence".into(); + assert!(verify(&m, &ctx).is_err()); + // A code rollback never lowers the remembered successfully activated floor. + ctx.minimum_release_sequence = 5; + assert!(verify(&manifest(), &ctx).is_err()); + ctx = context(); + ctx.minimum_release_sequence = 2; + assert!(verify(&manifest(), &ctx).is_err()); + ctx.active_release = None; + ctx.minimum_release_sequence = 4; + assert!(verify(&manifest(), &ctx).is_err()); +} + +#[test] +fn descriptor_roles_ids_bounds_and_digest_encoding_are_strict() { + let changes: [fn(&mut ReleaseManifest); 10] = [ + |m| m.release_id = Uuid::nil(), + |m| m.release_sequence = 0, + |m| m.version.clear(), + |m| m.version = "https://attacker.invalid/latest".into(), + |m| m.artifacts[0].artifact_id = Uuid::nil(), + |m| m.artifacts[1].artifact_id = m.artifacts[0].artifact_id, + |m| m.artifacts.swap(0, 1), + |m| m.artifacts[0].bytes = 0, + |m| m.artifacts[0].bytes = MAX_ARTIFACT_BYTES + 1, + |m| m.artifacts[0].sha256 = m.artifacts[0].sha256.to_uppercase(), + ]; + for change in changes { + let mut m = manifest(); + change(&mut m); + assert!(verify(&m, &context()).is_err()); + } +} + +#[test] +fn artifact_eof_extra_bytes_hash_and_io_errors_never_verify() { + let checked = verify(&manifest(), &context()).unwrap(); + for bytes in [b"agent imag".as_slice(), b"agent image!", b"agent imagX"] { + assert!( + checked + .verify_artifact(ArtifactRole::Agent, Cursor::new(bytes)) + .is_err() + ); + } + struct FailingReader; + impl Read for FailingReader { + fn read(&mut self, _: &mut [u8]) -> io::Result { + Err(io::Error::new(io::ErrorKind::PermissionDenied, "fixture")) + } + } + assert!( + checked + .verify_artifact(ArtifactRole::Agent, FailingReader) + .is_err() + ); +} + +#[test] +fn streamed_large_release_verifies_with_fixed_read_window() { + struct BoundedReader { + remaining: u64, + largest_read: usize, + } + impl Read for BoundedReader { + fn read(&mut self, output: &mut [u8]) -> io::Result { + self.largest_read = self.largest_read.max(output.len()); + assert!(output.len() <= 32 * 1024); + let size = self.remaining.min(output.len() as u64) as usize; + output[..size].fill(19); + self.remaining -= size as u64; + Ok(size) + } + } + let bytes = vec![19; 512 * 1024 + 7]; + let mut m = manifest(); + m.artifacts[0].bytes = bytes.len() as u64; + m.artifacts[0].sha256 = hash(&bytes); + let checked = verify(&m, &context()).unwrap(); + let mut reader = BoundedReader { + remaining: bytes.len() as u64, + largest_read: 0, + }; + checked + .verify_artifact(ArtifactRole::Agent, &mut reader) + .unwrap(); + assert_eq!(reader.remaining, 0); + assert_eq!(reader.largest_read, 32 * 1024); +} + +#[test] +fn keyring_rejects_weak_keys_duplicates_empty_sets_and_invalid_ranges() { + assert!(TrustedUpdateKey::new([0; 32], Platform::LinuxX64, 1, 10, false).is_err()); + let public = SigningKey::from_bytes(&[41; 32]).verifying_key().to_bytes(); + assert!(TrustedUpdateKey::new(public, Platform::LinuxX64, 0, 10, false).is_err()); + assert!(TrustedUpdateKey::new(public, Platform::LinuxX64, 10, 9, false).is_err()); + assert!(UpdateKeyring::new(0, vec![key(false, 1, 20)]).is_err()); + assert!(UpdateKeyring::new(1, vec![]).is_err()); + assert!(UpdateKeyring::new(1, vec![key(false, 1, 20), key(false, 1, 20)]).is_err()); +} diff --git a/docs/agent-updater-proposal.md b/docs/agent-updater-proposal.md new file mode 100644 index 0000000..116d659 --- /dev/null +++ b/docs/agent-updater-proposal.md @@ -0,0 +1,442 @@ +# Agent-Selbstupdate: kleinster zusätzlicher Schnitt + +Stand 2026-11-14, **Integrationsvorschlag mit implementiertem reinem Prüfkern**, +keine neue Produktnorm und kein Installations-/VM-Nachweis. Basis: +Spezifikation1.19, Kapitel0,4,13,16,19,22,25. +Der User möchte den Agent-Autoupdater jetzt parallel zur Skriptkonsole. Damit +wird ausschließlich dieser Teil aus M7 vorgezogen; Restore, HA, Relay und Lasttest +werden dadurch keine zusätzlichen MVP-Aufgaben. APT-/MSI-Fixturerezepte verwalten +andere Software und implementieren **keinen Agent-Selbstupdater**. + +## Verhalten und Genehmigung + +Der installierte Agent prüft regelmäßig, ob ein passendes, freigegebenes Release +vorliegt. Der erste Vorschlag ist ein täglicher passiver Metadatencheck mit +Jitter, zusätzlich beim Prozessstart, über den bereits konfigurierten Server. +Dies sammelt ausschließlich feste Release-Metadaten und startet keinen Job, +Installer, Download beliebiger URLs oder Codewechsel. Fehlende Konfiguration +meldet `not_configured`, abgelaufene Metadaten `unknown` samt Zeitpunkt/Fehler. + +Ein Update erhält eine eigene typisierte Aktion `update_agent`. UI/MCP dürfen +einen festen Plan vorbereiten und als `pending_approval` beantragen. Der Plan +bindet pro Gerät Release-Manifesthash, Artefakte, exakten Vorgänger, Plattform, +Versuch, Frist, Parallelitätsgrenze und erlaubte einmalige Wiederherstellung. +WebUI-Genehmigung, aktuelle Startprüfung und dauerhafter Einmalverbrauch bleiben +erforderlich. Ein Mensch kann einen festen Rollout gemeinsam genehmigen; +`latest`, zukünftige Versionen, Wildcardziele und periodische Selbstfreigabe +sind keine zulässigen ausführbaren Parameter. `updates:apply` wird zusätzlich +zu den jeweiligen Root-/SYSTEM-Rechten geprüft; eine Policy begrenzt nur. + +Der UI-Text muss Agent-/Helper-Dienstunterbrechung und mögliche Management- +Unterbrechung anzeigen. Dieser Schnitt fordert keinen Hostreboot an und darf +keinen Installer wählen, der ungeplant neu startet. Notwendiger Hostreboot +verlangt einen eigenen festen genehmigten Job. Automatischer Versionscheck, +freigegebener Rollout und bestätigter Updateerfolg bleiben getrennte Zustände. + +## Festes Releaseformat1 + +Ein Release besteht zunächst aus genau zwei Rohdateien: Agent und privilegierter +Helper. Kein Archiv, Postinstall-Skript, freier Pfad oder beliebiges Kommando. +Linux verwendet `x86_64-unknown-linux-gnu`, Windows +`x86_64-pc-windows-msvc`. Die Plattformkennung ist eine geschlossene Auswahl. +Ein neuer Updater selbst ist **nicht** Teil dieses ersten Selbstupdatepfads. +APT-/MSI-Pakete können später denselben signierten Vertrag umschließen; der +erste Rohbinaryschnitt darf nicht als APT-/MSI-Upgrade beworben werden. + +Das Envelope enthält `schema_version=1`, `key_id`, `payload_bytes` und +`signature` (feste Ed25519-Signatur,64Bytes). Für JSON-Transport werden +`payload_bytes` und `signature` als kanonisches Base64url ohne Padding übertragen, +keine unbeschränkten Zahlenarrays. Der erste Bibliothekskern nimmt bereits +dekodierte begrenzte Bytes entgegen; die spätere Transportintegration muss das +Envelope vor Decodierung begrenzen. Der Payload ist streng typisiertes +JSON mit festen Feld-/Listenreihenfolgen, ohne unbekannte Felder, doppelte Keys, +Floats oder alternative Encodingform. Nach Parsen muss exakt dieselbe kanonische +Serialisierung entstehen. Signaturbytes sind die Domäne +`rmm.agent-release.v1\0` gefolgt von den unveränderten Payloadbytes. Der +Manifesthash ist SHA256 derselben Payloadbytes. Verifikation begrenzt das +Payload vor Parsen auf16KiB und verwendet `verify_strict` aus dem schon gepinnten +`ed25519-dalek=2.2.0`; keine Algorithmusverhandlung. + +| Payloadfeld | Festgelegte Bedeutung | +|---|---| +| `schema_version` | Genau1 | +| `release_id` | UUID; unveränderlicher veröffentlichter Datensatz | +| `release_sequence` | Positive monotone Veröffentlichungsnummer je Plattform; Versionsvergleich nutzt diese Nummer | +| `version` | Sichtbare nichtleere ASCII-Versionskennung; kein lexikografischer Semververgleich | +| `platform` | Eine der beiden festen x64-Plattformkennungen | +| `published_at`, `expires_at` | UTC-Epochsekunden, gültig nur mit vertrauenswürdigem Clockkontext | +| `protocol_major` | Exakte unterstützte Hauptversion; die erste Stufe erlaubt nur dieselbe aktuelle Version | +| `state_schema` | Exakte kompatible Zustandsversion; erste Stufe erlaubt **keine** Zustandsmigration | +| `minimum_updater_version` | Positive numerische Implementierungsversion des unabhängigen Updaters | +| `artifacts` | Genau Agent, danach Helper; je `role`, unveränderliche `artifact_id`, SHA256 und Länge | + +Artefakthashes sind64kleine Hexzeichen; Längen positiv und höchstens256MiB pro +Datei. Artefakt-UUIDs dürfen nicht doppelt sein. Rollen sind `agent` und `helper`, +keine eigenen Dateinamen aus dem Netzwerk. Die Veröffentlichung ist erst +verfügbar, wenn beide vollständigen Dateien existieren und deren Hash/Länge +mit dem signierten Manifest übereinstimmen. Serverkatalog und Tenantberechtigung +bestimmen Sichtbarkeit; das Manifest selbst verleiht keinerlei Ausführungsrecht. + +## Vertrauen, Ablauf und Versionsschutz + +Update-, Job-/Grant- und Geräte-/TLS-Schlüssel sind getrennt. Lokaler Bootstrap +provisioniert einen root-/SYSTEM-geschützten Update-Keyring mit SHA256-Key-ID, +rohem32Byte-Publickey, Plattformbindung und zulässigem Sequenzbereich. Kein +Schlüssel aus einem Job, Manifest oder Download wird automatisch vertrauenswürdig. +Veraltete/gesperrte Keys verweigern auch eine ansonsten passende Signatur. + +Erste kleine Stufe unterstützt Rotation/Widerruf durch kontrollierte, separat +provisionierte Keyringgeneration; neue Generation muss größer sein, alte +Schlüssel werden nicht implizit übernommen. Dynamisches Online-Rootrotation- +Protokoll ist noch offen und wird nicht als TUF-Implementierung ausgegeben. +Dies hat eine konkrete Grenze: Ein lange isolierter Client kennt einen späteren +Widerruf erst bei frischer authentisierter Trustprovisionierung. Daher beginnt +ohne frischen Kontakt und aktuellen Trustkontext kein Apply. + +Lokal gibt es getrennt (a) die aktuell aktive Manifest-ID/Sequenz, (b) die höchste +erfolgreich aktivierte Sequenz als Antirollbackgrenze, (c) den höchsten gesehenen +Katalogstand für Replaydiagnose und (d) einen offenen Übergabeintent. Bloßes +Ansehen eines neuen Releases autorisiert keine Wirkung. Ein älteres Release +unter der bestätigten Antirollbackgrenze ist niemals ein neues Updateziel. +Gleiche Sequenz mit anderen Manifestbytes ist ein Konflikt; dieselben Bytes sind +ein Metadatenduplikat, keine neue Wirkung. Versionslabels allein reichen nicht. + +`verify_release` prüft ausschließlich **zukünftige Updatekandidaten**. Nach +einem Code-Rollback (`active=3`, bestätigter Floor=5) verweigert diese Funktion +auch das aktive Manifest3 als erneutes Updateziel. Das bedeutet keine Korruption +oder Ungesundheit der aktuell laufenden Version. Passive Anzeige und Health +verwenden den gesonderten geschützten `InstalledReleaseRecord` mit explizitem +Rollbackstatus; sie dürfen diese Kandidatenprüfung nicht als Current-Healthcheck +verwenden. `SameActiveManifest` ist nur oberhalb/auf dem unveränderten Floor +erreichbar und bleibt ausschließlich ein Metadatenvergleich. + +Die einzige Rückkehr zu einer niedrigeren aktiven Sequenz ist die im selben +genehmigten Versuch vorab gebundene letzte bekannte Codeversion, deren Dateien +noch unverändert lokal vorhanden sind. Die Antirollbackgrenze wird dabei nicht +gesenkt. Widerrufene/ausdrücklich verbotene Vorgänger werden auch als Rollback +verweigert. Ein späteres Downgrade verlangt einen getrennten Recoveryvertrag. + +## Servertransport und UI/MCP-Vertrag + +Vorgeschlagener zusätzlicher lesender Endpunkt: +`GET /agent/v1/releases/current?platform=`, über vorhandenes +Geräte-mTLS, ohne Redirects, höchstens32KiB Envelope, Serverzeit und Katalog- +beobachtungszeit getrennt. Antwort enthält einen signierten festen Manifestenvelope +oder explizites `not_configured`/keine angebotene Version. Kein neuer öffentlicher +Login oder allgemein adressierbarer Installerdownload. Ein veraltetes aber noch +gültiges Manifest ist durch reine TLS-/Hashprüfung allein nicht als aktuellste +Version beweisbar; der Check meldet nur die tatsächlich beobachtete Version. + +Der vorhandene geräte-/Job-/Versuch-gebundene +`/agent/v1/artifacts/{artifact_id}`-Pfad kann derzeit nur Artefakte bis256KiB +beziehen: `LocalArtifacts::put/get` **und** das SQL-`CHECK` in +`migrations/0006_catalog.sql` begrenzen sie entsprechend. Sein512KiB- +Chunklimit erweitert weder Store noch SQL und lädt heute das ganze Objekt in +einen `Vec`. +**Damit kann er Agentbinaries nicht transportieren.** Die bis256MiB großen +Deskriptoren des neuen reinen Prüfkerns sind für eine noch offene, ausdrücklich +Update-spezifische begrenzte Streaming-Erweiterung vorgesehen. Weder Import, +Downloadroute noch Serverlimit werden in diesem Schnitt verändert. Spätere +Integration muss dieselben Geräte-/Job-/Versuchs- und exakten Manifestbindungen +auch für große Streams durchgehend erhalten. Kein vom LLM gelieferter +Downloadhost, TCP-Override, Dateipfad oder TLS-Ausnahmeschalter. +Der zukünftige Download wird gestreamt und vor Verwendung gegen +Länge/SHA256 geprüft; Zusatzbytes und vorzeitiges EOF verweigern. Nach Reconnect +stammt neue Startautorität immer aus dem normalen Plan-/Grantpfad. + +`operations.plan(action=update_agent)` erhält nur die gespeicherte Release-ID +und feste Ziele; Server löst unveränderliche Bytes aus dem berechtigten Katalog +auf und bindet tatsächlichen gespeicherten Vorgänger sowie beide Artefakte. +`operations.submit` bleibt Antrag; `jobs.get` zeigt Staging, Übergabe, +Dienstprüfung, erhaltene Identität, Rollback und tatsächlichen Ausgang. Vor +Genehmigung zeigt WebUI alle Hashes, Versionen, Rechte und Ausfall-/Rollbackgrenzen. +Neue Datenverträge sind mit dem Skriptkonsolen-Eigentümer abzustimmen; dieser +Vorschlag ändert noch keine Domain-/Protokoll-/Server-/Webdatei. + +## Unabhängiger Worker und erhaltende Übergabe + +Der Netzwerkagent bleibt unprivilegiert. Ein kleiner separat installierter +Updater wird unter Root/SYSTEM mit restriktiver IPC/Peerprüfung angesteuert. +Er prüft selbst Releasekey, Manifest, exakten Originaljob/-grant, aktuelle +Identitäts-/Zuordnungs-/Boot-/Clock-/Syncbindung und lokalen Policykontext. +Die schon vorhandenen Helperprüfungen dürfen nicht durch bloßes `approved=true` +oder einen Dateimarker ersetzt werden. Sein eigener Journal-/Verbrauchsbezug +muss vor Start serverseitig bekannt und unabhängig synchronisiert sein. + +Der Updater startet nicht aus der gerade zu ersetzenden Agent-/Helperdatei und +überlebt deren Stop. Geräteweite Locks serialisieren Paketmanager, Updates, +Root-/SYSTEM-Skriptwartung und Reboots. Offene oder unbekannte Versuche sperren +die erste Updateversion; keine Aktualisierung mitten in einer Wirkung. + +1. Exakten Vorgänger, Trust-/Policy-/Serviceidentitäten, freie Kapazität und + Zustandskompatibilität prüfen. Geschützte Stagingdateien create-only auf + demselben Dateisystem; Files und Verzeichniseinträge dauerhaft flushen. +2. Manifest und beide Dateien unabhängig prüfen; keine Wirkung vor Genehmigung. + Ein Downloadfehler vor Übergabe bleibt belegter Nichtstart der Aktivierung. +3. Vor Stop/Swap dauerhaften Intent mit Originaljob/Versuch/Grant und allen + Vorherzeugen schreiben, Grant/Versuch einmalig verbrauchen. Nach unklarem + Ausgang ausschließlich Zustand desselben Intents lesen, nie Execute wiederholen. +4. Dienste geordnet einmal stoppen; aktive handles/Locks und SQLiteintegrität + prüfen. Identitäten, Geräteschlüssel, Zertifikats-/Rotationstore, Konfiguration, + ACLs, DBinodes/FileIDs, Originaltabellen/-zeilen, Journale/Signaturen und offene + Outbox bleiben erhalten. Private Schlüsselbytes werden nicht exportiert. +5. Für den ersten Aktivierungsschnitt empfehle ich **bestehende feste + Service-Imagepfade erhalten**. Der unabhängige Updater stoppt und bestätigt + beide Dienste, tauscht alle gebundenen Code-/Pin-Dateien unter den Locks, + prüft vollständig die neue Kombination und startet erst dann einen Dienst. + So läuft kein altes/neues Paar gleichzeitig, obwohl die Dateiersetzungen + **kein atomarer Dateisystem-Bundleswap** sind. Der dauerhafte Intent benennt + jede bereits erfolgte Ersetzung; ein Absturz lässt beide Dienste bis zum + eindeutig belegten Abschluss oder Code-Rollback gesperrt. Vorhandene Runner + zeigen dieses Wartungsfenster bereits, sind aber noch kein Selfupdater. + Ein neuer Launcher würde Service-PID-/Image-/Peerprüfungen verändern und ist + für diesen ersten Schnitt unnötig. Ein einzelner atomarer Versionsselector + bleibt eine spätere Alternative mit eigener vollständiger Qualifikation. +6. Neue Dienste einmal starten; actual Imagehash/Identität, passive Heartbeats, + bestätigtes Inventar und erfolgreiches signiertes Sync mit geschlossenen + Effectgates bis zum vollständigen Abgleich nachweisen. `Running` allein reicht + nicht. Erst dann aktives Release/Antirollbackgrenze dauerhaft bestätigen. +7. Bekannter Fehlstart darf genau die vorab gebundene Codeversion einmal + zurückselektieren und starten; derselbe aktuelle Datenzustand bleibt liegen. + Keine DB-/Ledger-/Generation-/Clock-/ACLrücksetzung. Fehlender/unklarer + Rückkehrnachweis bleibt `unknown`, keine Schleife automatischer Startversuche. + +Vorhandene SSH-Bootstraprunner (`vm_runtime_upgrade.py`, +`cloud_shared_core_upgrade_v2.py`, `windows/runtime_feature_upgrade.py`) zeigen +nützliche erhaltene DB-/Inode-/FileID-/Schlüsselmetadatenprüfungen und dauerhafte +einmalige Intents. Sie sind administrative Einzeltools, keine ausgelieferten +Selfupdater und keine Ersatzgenehmigung dieses Produktpfads. Frühere fehlerhafte +Verifierberichte bleiben historisch; neue Abnahme muss konkrete aktuelle Daten +binden, einschließlich vorhandener zulässiger Hardlinkpublikationen. + +## Kleinster prüfbarer Quellschnitt und danach offene Arbeit + +Nach Entwurfsreview implementiert: neue kleine `crates/updater`-Bibliothek, +keine Daemonhülle. Dateien `Cargo.toml`, `src/lib.rs`, `src/manifest.rs` und +neun gezielte Vertragsprüfungen mit vollständiger kanonischer Goldenfixture. +Root-`Cargo.toml`/`Cargo.lock` nur für Workspacebindung; keine neuen fremden +Paketversionen. Alle benutzten Abhängigkeiten waren bereits im Lockfile. +Implementierte Funktion: bounded canonical manifest decode, strikte Ed25519-Verifikation gegen +getrennten übergebenen Keyring, Plattform-/Clock-/Kompatibilitäts-/Versionsprüfung +und begrenzte Streaming-Hash-/Längenprüfung von Artefakten. Keine Aktivierung, +kein Netzwerk, keine generische OS-Dateischreib-API. Ein validiertes Objekt +beweist nur gültige Releasebytes; dessen API darf weder Approval noch Startgrant +behaupten oder aus dessen Besitz ein Applyrecht ableiten. + +Der Kern wurde mit echten lokalen Signaturen und manipulierten/alten/falschen +Releasebytes geprüft, ohne einen Agenten auf dem Notebook zu starten. +Danach bleiben explizit offen: Serverkatalog/Veröffentlichung und echter +Releasekeybetrieb, täglicher Agentcheck und gespeicherte Updatebeobachtung, +typisierte Plan-/Grant-/UI-/MCP-Bindung, getrennte Updater-Verbrauchssynchronisation, +geschütztes OS-Staging, unabhängiger Updaterbootstrap, mehrstufiger Dateiaustausch, +Health-/Rollbackpfad, echte Linux-VM-Abnahme zuerst und Windows-VM-Abnahme danach. +Ein Bibliotheksbuild ist weder Autoupdaterinstallation noch AT-26-/MVP-Erfolg. + +Tatsächlich ausgeführt: vollständige Pflichtnormen gelesen und vorhandene +Upgrade-/Kryptoverträge untersucht; eigener isolierter Worktree ab287a784. +Der vorhandene Dockerbuilder mit Rust1.99.1 wurde offline, ohne Netzwerk und +mit nur lesbarem Quellmount verwendet, eigener Targetausgabe. Image-ID: +`sha256:9a76ad3744ebfdddae96ca10001ce8291c1b332fb54c8df5eea0e8e999ac6fc6`. +Alle folgenden Prüfungen bestanden für `x86_64-unknown-linux-gnu`: + +```text +cargo fmt --manifest-path /src/Cargo.toml -p rmm-updater -- --check +cargo clippy --manifest-path /src/Cargo.toml --locked --offline --target x86_64-unknown-linux-gnu -p rmm-updater --all-targets -- -D warnings +cargo test --manifest-path /src/Cargo.toml --locked --offline --target x86_64-unknown-linux-gnu -p rmm-updater --all-targets --release +``` + +Neun ausgeführte Vertragsprüfungen bestanden ohne Skip. Sie prüfen feste +kanonische Bytes, echte domänengetrennte Ed25519-Signaturen, falschen/gesperrten +Key und dessen Sequenzbereich, unbekannte/doppelte Felder,16KiB-Grenze, +Plattform/Clock/Trustgeneration/Protokoll/Zustand/Updaterkompatibilität, +Versionsfloor und gleichen Sequenzkonflikt, exakt zwei Artefaktrollen, +Hash-/EOF-/IOfehler sowie512KiB+7Bytes mit tatsächlichem32KiB-Readlimit. +Der verwendete private Testsignierschlüssel ist ausschließlich eine feste +öffentliche Testfixture und wird nie als Vertrauensanker ausgeliefert. + +Lokaler Beleg (gitignored): `devstate/agent-updater/local-qualification.json` +bindet Quellen, Image-ID, tatsächliche Befehle/Loghashes und alle neun Testnamen. +Die Linux-Release-Testexe ist1544584Bytes groß, SHA256 +`e3a1a3140da09de2f86055faa45faf7ba05ddddc2d92d23fef3df03a63bf2999`. +Das ist ein lokaler Container-/Vertragsnachweis, **kein Cloud-VM-Nachweis**. +Native Linux-Test-VM vor Windows, Serverintegration und tatsächlicher +genehmigter Codewechsel bleiben offen. Kein Installer-/VM-Aufruf, keine +Dienständerung, keine Freigabe und kein RMM-Job durch diesen Quellschnitt. + +## Nächster Integrationsschnitt zur Freigabe: fester Codepaar-Updatejob + +Die folgende Änderungsliste ist **nur Entwurf, nicht implementiert**. Sie +ersetzt keine Sourcefreigabe, Bootstrapabstimmung oder native Abnahme. Mit dem +Skriptkonsolen-Eigentümer abgestimmt: `update_agent`, `agent.update.apply/1` +und `updates:apply` kollidieren nicht mit `full_maintenance_v1`. Dessen separater +Helperpfad und das allgemeine/APT-Profil bleiben getrennt; alle benutzen dieselbe +geräteweite Wirkungssperre und erhaltene Verbrauchshistorie. + +### 1. Unveränderliche Action und Planbindung + +Vorgeschlagene additive `Action::UpdateAgent { update: ResolvedAgentUpdate }`, +eigener Modulvertrag `crates/domain/src/agent_update.rs`. Kein Aufruf von +`run_script`, APT oder MSI. Alte Action-/Job-/Plan-/Grantbytes bleiben exakt +erhalten. `JobPayload` behält seine bestehenden IDs, Identitätsgenerationen, +Zeitgrenzen und Limits; `ExecutionPermit.action` lautet `update_agent` und +bindet wie bisher den gesamten `job_payload_hash`. Vor Genehmigung erzeugt +der Server die vollständigen Bytes je festem Ziel/Versuch. + +`ResolvedAgentUpdate` hat in dieser festen kanonischen Feldreihenfolge: + +| Feld | Typ und Bindung | +|---|---| +| `schema_version` | Genau1 | +| `profile` | Genau `fixed_code_pair_v1` | +| `release_envelope` | Schema1, Update-Key-ID, Payload/Signatur als Base64url ohne Padding; keine freien URLs | +| `release_envelope_sha256` | SHA256 des kanonischen vollständigen Envelopes, einschließlich Signatur/Key-ID | +| `manifest_sha256` | SHA256 der dekodierten exakten Release-Payloadbytes | +| `predecessor` | Feste Release-ID, Sequenz, Manifesthash, `installed_record_sha256`, Agent-/Helperhash | +| `updater` | Exakter installierter Updaterbinaryhash, lokale Policyhash, Keyringgeneration und Keyringhash | +| `peer_pin_transition` | Typisierte Plattformvariante, feste Vorher-/Nachher-Settings-/Pinhashes; siehe unten | +| `recovery` | Genau `restore_exact_predecessor_once` | +| `health_profile` | Genau `mtls_inventory_sync_v1` | +| `health_timeout_seconds` | Genau180 im ersten Schnitt; gesamter Job maximal600Sekunden | +| `no_reboot` | Genau `true` | + +Die beiden Artefakte und ihre Reihenfolge kommen ausschließlich aus dem signierten +Manifest. `artifact_ids` als zusätzliche Requestparameter sind für diese Action +verboten. Der Plan enthält je Job/Versuch genau die beiden daraus abgeleiteten +`JobArtifactReference`s; generisches Nachladen weiterer Dateien ist verweigert. +Weil die bisherigen Resolver kleine `artifacts` voraussetzen, erhält ausschließlich +`update_agent` einen eigenen Resolver gegen den Updatekatalog. Alte Resolver und +ihre Grenzen bleiben bestehen. Fehlende/doppelte/fremde Referenzen, geänderter +Vorgänger oder ein von der Plattform abweichendes Release sperren bereits Planung +und nochmals Submit, WebUI-Genehmigung, Revalidation, Startgrant und Download. +Der vollständige Job muss weiter in die vorhandene64KiB-Helpergrenze passen. + +Erste Einrichtung importiert die tatsächlich installierte bekannte Codepaar- +Baseline als separat release-signierten Datensatz mit eigener Sequenz, prüft +ihre Dateien und provisioniert daraus `InstalledReleaseRecord` und Floor. +Dadurch besitzt auch das erste Update einen exakten bekannten Vorgänger; kein +`unknown`, frei vom Agenten behaupteter Hash oder ungeprüftes Legacy-Downgrade. +Dies ist Teil des gesonderten erhaltenden Updaterbootstraps, kein Codeupdate. + +Windows benötigt einen festen Pure-Renderer: ausschließlich +`Settings.agent.binary_sha256` und `Settings.helper.binary_sha256` werden aus +den Zielartefakten ersetzt; alle Rechte, Dienste, Identitäten, Pfade, Runtime- +und Clockflags bleiben gleich. Der daraus kanonisch abgeleitete Settingshash +und öffentliche `Pin`-Hash stehen **vor Genehmigung** fest. Grundlage ist ein +typisierter aktueller öffentlicher Deploymentbeleg des bestehenden Helpers, +keine Secretdatei. Der lokale Updater prüft vor/nach unabhängig, dass exakt diese +beiden Felder geändert werden. Der Server darf nur die exakt genehmigte neue +Code-/Policybindung aktivieren; dadurch entstehen keine neuen Aktionsrechte. +Linux verwendet bei unverändert codeunabhängigen Generalpins die Variante +`unchanged_general_pin_v1`. APT-Akzeptanzbelege werden nicht neu signiert oder +als für neue Codebytes gültig ausgegeben; gegebenenfalls bleibt APT geschlossen. +Nicht unterstützte weitere Pinprofile sperren dieses erste Update, statt sie +automatisch mitzunehmen oder neue Akzeptanznachweise zu erfinden. + +### 2. Rechte, Beobachtung und Capability + +Planurheber und Freigeber benötigen jeweils die üblichen Operationsrechte plus +`updates:apply` und Linux `root:execute` beziehungsweise Windows `system:execute`. +`scripts:execute` wird nicht daraus abgeleitet. Eine zusätzliche versionierte +zentrale/local-Updaterpolicy begrenzt exakte Geräte-/Generations-/Principal-, +Updater-/Keyring-/Manifest-/Vorgänger- und Pinbindungen. Standard bleibt deny. +Die WebUI zeigt Ziel und Vorgänger, beide Binärhashes, Rechte, Unterbrechung, +Rollback, Pinänderung und Fristen; MCP verwendet nur Plan/Submit/Status. + +`agent.update.check/1` wird nach tatsächlich funktionierendem reinem Metadaten- +Check gemeldet. `agent.update.apply/1` erst nach nativer aktueller Qualifikation +des installierten unabhängigen Updaters, IPC-/Peer-/Lock-/Ledgerprüfung und +bestätigtem signiertem Sync. Ein Librarybuild erzeugt keine Capability. Check +speichert Quelle, tatsächlich beobachteten Manifesthash, Zeit, Qualität und +`available`/`same`/`not_configured`/`error`; er lädt keine großen Dateien und +legt weder Jobs noch Outbox für Wirkungen an. `rolled_back` beim installierten +Record ist von der angebotenen Kandidatenversion getrennt sichtbar. + +### 3. Begrenzter Releasekatalog und eigener großer Artefaktpfad + +Neue immutable Tenanttabellen `agent_releases` und `agent_release_artifacts` +mit zusammengesetzten Tenant-FKs, RLS/FORCE-RLS und ohne UPDATE/DELETE für die +Anwendungsrolle. Release-ID/Sequenz/Plattform sind eindeutig; Publizieren +verifiziert Signatur, kanonische Bytes, Rolle, Länge und Hash beider Dateien. +Keine Änderung am262144Byte-`CHECK` der bestehenden `artifacts`-Tabelle. +Ein tenantgebundener `AgentReleaseStore` arbeitet mit bereits geprüften +content-addressierten, unveränderlichen Objekten und begrenzten Readhandles; +kein `get()->Vec` für bis256MiB. Publikation ist ein Plattformbetriebsrecht, +kein vom Modell befüllbarer allgemeiner Upload-/Signierdienst. + +Neuer `GET /agent/v1/update-artifacts/{artifact_id}` mit `job_id`, `attempt_id`, +`offset`, `length`: Geräte-mTLS, genau genehmigter aktueller `update_agent`-Job, +aktuelle Tenant-/Geräte-/Generations-/Rechte-/Planbindung und exakt eine der +beiden Referenzen. Jeder Chunk prüft diese Bindung erneut; höchstens512KiB, +Gesamtobjekt höchstens256MiB, begrenzte Parallelität/IOzeit und kein Redirect. +`Content-Range`, Gesamtgröße und SHA256 sind an den Deskriptor gebunden. +Server verifiziert Objektidentität/-länge vor Read und streamt begrenzt; +Agent/Updater prüft unabhängig den vollständigen Gesamt-SHA256 und exaktes EOF. +Nach Antwortverlust dürfen nur fehlende Downloadbytes desselben geschützten +Stagingobjekts weiterbezogen werden, niemals ein neuer Installer-/Aktivierungs- +versuch. Eine fortgesetzte Datei wird vor Verwendung vollständig neu gehasht. + +### 4. Stabiler Updater, einmalige Übergabe und Absturzverhalten + +Separat bootstrapped stabiles Updaterbinary; dieser erste Updatejob verändert +es nicht. Feste Linux-UID-/Windows-Dienst-SID-/PID-/Image-/ACLprüfungen, keine +vom Agenten gewählten Programme/Pfade. Bestehende Agent-/Helper-Servicepfade +bleiben erhalten. Alle tatsächlich installierten Profile, die dieselbe +Helperbinary verwenden, müssen im fest provisionierten Dienstset stehen und +vor Austausch bestätigt gestoppt sein; unbekanntes Profil verweigert. Der +Updater gehört selbst nicht zu diesem Stopset. + +Die erste Empfehlung ist **denselben bestehenden Helperverbrauchsledger und +`executor.lock`** zu verwenden, wie heute schon mehrere Helperprofile, statt +einen ungebundenen neuen Ready-/SQLitepfad zu eröffnen. Bootstrap fügt nur eigene +append-only Updateintents hinzu, ohne alte Zeilen/Schemaobjekte zu ersetzen. +Updater prüft seinen aktuellen Prozess-/Boot-/Clock-/Signatur-/Syncbezug selbst; +ein anderer Prozess vererbt keine Bereitschaft. Ob der vorhandene gemeinsame +Helpersnapshot dies ohne Wireerweiterung vollständig bindet, ist vor Runtime- +Code anhand `HelperSync`/`ExecutorLedgerGuard` zu prüfen. Falls nicht, bleibt +Apply geschlossen bis zu einer separat versionierten Participantbindung; +kein weiterer Journal-ID-Slot wird stillschweigend in alten Tags versteckt. + +Der Updater darf seinen eigenen Updateversuch nach Verbrauch als einzigen +offenen Versuch führen; jeder **andere** offene/unknown-/unsettled-Versuch +sperrt. Root-/SYSTEM-Wartungsskripte und Paket-/Rebootwirkungen verwenden +dieselbe Sperre. Nach Übergabe überlebt der Updater Agent-/Helperstop und +journalisiert im eigenen erhaltenen Intent die folgenden Phasen: + +| Phase | Dauerhafter Beleg und zulässige Folgerung nach Absturz | +|---|---| +| `staged_verified` | Nur geprüfte Dateien vorhanden, noch kein Stop/Swap; Nichtstart nur mit unabhängig belegtem Nichtdispatch | +| `handoff_consumed` | Originaljob/Grant/Versuch und vollständige Vorherzeugen fest, kein zweites Execute | +| `stop_intent` / `all_stopped` | Einmaliger Stop angekündigt/bestätigt; unklare Dienste erst lesen, nicht blind erneut stoppen/starten | +| `replace_intent(role)` / `replaced(role)` | Jede einzelne Code-/Pinersetzung bindet Original-/Zielhash, ACL und retained Backup; tatsächliche Datei entscheidet über Teilzustand | +| `pair_verified` | Gesamtes neues Code-/Pinset vollständig geprüft, vor jedem neuen Dienststart | +| `start_intent(service)` / `started(service)` | Jeder Start nur einmal, tatsächliche SCM-/systemd-/PID-/Imagebelege, kein Retry bei verlorenem Reply | +| `health_verified` | Neues mTLS, tatsächlicher Codepaarbeleg, Inventar-ACK und signierter Sync für selben Originalversuch innerhalb180Sekunden | +| `rollback_intent` / `rollback_verified` | Ausschließlich gebundene Originalcode-/Pinbytes einmal zurück, gleicher aktueller Datenzustand und unveränderter Floor | +| `outcome_persisted` | Originalerfolg oder bekannter Fehlstart samt Rollbackresultat dauernd gespeichert; unverändert bis ACK erneut übermitteln | + +Anwendungsweite Effectgates bleiben während Wechsel und Health geschlossen; +der eigene bereits verbrauchte Updateversuch darf gezielt abgeglichen werden, +ohne dadurch neue allgemeine Starts zu erlauben. Sonst würde die eigene offene +Updatezeile Health-Sync dauerhaft blockieren. Nach frischem Prozessstart ist +kein alter Gate-/Leasezustand gültig. Ein unbekannter Teiltausch/Start bleibt +`unknown`; Recovery liest vorhandene Dateien/Intents und darf daraus keine +neue Wirkungserlaubnis konstruieren. Allgemeines Resume bei ungeklärtem +Dispatch und Endlosschleifen automatischer Rollbacks gehören nicht dazu. + +### 5. Konkrete Datei-/Abnahmefolge nach erneutem Review + +| Lieferung | Geplanter enger Dateiscope und überprüfbares Ergebnis | +|---|---| +| Gemeinsamer Vertrag | Additives `domain/src/agent_update.rs`, zugehörige `Action`-Matches und Golden-/Legacyfixtures; `updater` bleibt eigenständiger Verifier, keine OSwirkung | +| Katalog und feste Planung | Neue Migration, `server/src/agent_releases.rs`, eigener Store/Streaminghandler, begrenzte Ergänzungen in `jobs`, `job_gateway`, Policy und MCPschema; alte Paketlimits bleiben bestehen | +| Passive Agentbeobachtung | Bestehende Transport-/Inventarworker ergänzen festen Releasecheck und gespeicherte Beobachtung; keine angeforderte Liveaktion als Telemetrie tarnen | +| Geschlossener Updaterworker | Neues unabhängiges Binary/OSadapter und versionierte Bootstrapdefinition, feste IPC/Locks/Ledger/Intents/Pinrenderer; keine offenen neuen Capabilities vor Qualifikation | +| Linux-Abnahme zuerst | Reine Kernunits nativ auf Cloud-Linux; danach ein fixes WebUI-genehmigtes Update samt getrennten belegten Fehler-/Redelivery-/Stateerhaltungsfällen | +| Windows danach | Native Kern-/IPC-/SCM-/Pin-/Codepaar-/Rollbackabnahme auf Windowsgast, dieselbe WebUI-/Tenantgrenze; keine Notebookdienste | + +Vor Runtimefreigabe sind vor allem gemeinsamer Syncteilnehmer, exakt erlaubte +Pinprofile und erfolgreiche Health bei ausschließlich eigenem offenen +Updateversuch zu entscheiden. Diese Liste enthält keine neue Terminalengine, +generischen Paketprovider, Keyrotationplattform, Restorefunktion oder weiteren +Produktumfang. Alle genannten Dateien/Befehle/Abnahmen dieses Abschnitts sind +**geplant, nicht ausgeführt**.