feat: add pure signed agent release verifier without apply authority
Rust development slice / linux (push) Failing after 7s

This commit is contained in:
2026-11-14 15:55:45 +01:00
parent 287a784c8f
commit cc5c93596d
8 changed files with 1185 additions and 1 deletions
Generated
+13
View File
@@ -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"
+1 -1
View File
@@ -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"
+14
View File
@@ -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
+12
View File
@@ -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,
};
+385
View File
@@ -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<Self> {
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<String, TrustedUpdateKey>,
}
impl UpdateKeyring {
pub fn new(generation: u64, keys: Vec<TrustedUpdateKey>) -> Result<Self> {
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<ActiveRelease>,
}
#[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<VerifiedRelease> {
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))
}
+1
View File
@@ -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}]}
+317
View File
@@ -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<VerifiedRelease> {
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<VerifiedRelease> {
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<usize> {
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<usize> {
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());
}
+442
View File
@@ -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=<feste-plattform>`, ü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<u8>` 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**.