385 lines
22 KiB
Markdown
385 lines
22 KiB
Markdown
# Typed RootHelper bridge contract (implementation, not native acceptance)
|
|
|
|
## Host reboot evidence and historical configured effect (Spec 1.13)
|
|
|
|
An ambient `reboot_required=true` is honest pending evidence, not an implicit
|
|
reboot request or a failed package postcondition. Future fixture effects must
|
|
prove equal HOST flags before/after, unchanged boot and no private-worker flag.
|
|
|
|
The parent captures `active/host-reboot-before.json` **before unshare/private
|
|
`/run`**. Schema 1 fields are `transaction_sha256`, `job_payload_sha256`,
|
|
`effect_armed_ledger_id`, `grant_id`, `boot_id`, `host_reboot_required` (bool),
|
|
and `observed_at_ms`, plus `schema_version`. Creation is exclusive and fsynced;
|
|
its observation must belong to the original grant window. New native prechecks
|
|
use schema 2, retaining the old exact checks and adding
|
|
`host_reboot_before_sha256` and `host_reboot_required_before`. The child binds the
|
|
saved host observation; its private `/run` never measures the host flag.
|
|
|
|
After real APT success the parent verifies the current host flag equals the
|
|
saved value, boot is unchanged and `sandbox-result.reboot_required` is false.
|
|
False/false and true/true are valid; either change or a private-worker flag
|
|
vetoes acceptance. Outcome evidence includes `host_reboot_required_before`,
|
|
`host_reboot_required_after`, `host_reboot_before_sha256`,
|
|
`reboot_required_introduced:false`; `reboot_required` truthfully retains ambient
|
|
true. Ordinary acceptance record **schema 3** explicitly binds those fields and
|
|
`native_prechecks_schema_version:2`. The reader rejects old record schemas or
|
|
inconsistent values. Separate future recovery records use schema 2 and retain
|
|
their distinct `rmm.apt.native-recovery` type. Noop observations remain effect-free
|
|
and report their actual current reboot flag. Fresh planning adds the required
|
|
public bool `host_reboot_required`; known ambient true is shown in the fixed
|
|
WebUI plan reason.
|
|
|
|
Historical grant `33775478-15b0-46ec-b059-44f500dbb0b6` had **no host-before
|
|
sample**. It must never acquire retroactive success or an acceptance record.
|
|
Fixed mode `verify-configured-recovery` receives the same eight original binding
|
|
fields as `verify-partial`. Only its signed schema-4 configure-only job, old
|
|
provider `5ff260…`, old schema-1 prechecks, original partial grant `31ef5e5e…` /
|
|
proof `dc3bf387…`, preserved recovery once marker, exact Configure hook, APT exit
|
|
0 and private-worker false are eligible. It checks complete stable installed
|
|
1.0 state, clean audit, actual payload, unchanged boot, idle locks and current
|
|
host marker contents twice, rechecking all thirteen immutable witnesses.
|
|
|
|
Output is `known_failed` /
|
|
`APT_RECOVERY_CONFIGURED_ACCEPTANCE_REBOOT_FLAG_VERIFIED`. Its 24-field proof
|
|
contains the original eight bindings, type/schema, original evidence digest,
|
|
partial proof hash, original baseline and current snapshot hashes/fingerprint,
|
|
payload hash, full snapshot, check time, `effect_complete:true`,
|
|
`partial_effect:false`, `postconditions_passed:false`, `reboot_required:true`,
|
|
`host_reboot_required:true` and `host_reboot_marker_sha256`. No ctime-based
|
|
inference becomes a before measurement. It writes nothing and runs no package
|
|
mutation. Rust independently verifies the saved signature/old unknown code,
|
|
appends a separate immutable proof, and leaves consumption locked until normal
|
|
signed RootSync. Native classification and future 1.1 acceptance remain pending
|
|
until actually executed; **81 local Python tests passed**, including both actual
|
|
APT argument regressions under the readonly unprivileged offline container.
|
|
|
|
## Configure-only partial recovery (schema 4, local implementation)
|
|
|
|
This is a **new, separately WebUI-approved** dev-test native action. Schema 4
|
|
requires `native_recovery = {schema_version:1, previous_grant_id,
|
|
previous_attempt_id, partial_proof_sha256}` and forbids `native_retry`.
|
|
Resolved transaction schema 2 adds `operation:"configure_only"`; only the
|
|
existing `rmm-apt-fixture-install-1.0` recipe/version 1, pinned fixture archive,
|
|
and old/new version `1.0` are eligible. Schema 1 retains its exact encoding.
|
|
|
|
The helper first requires the original saved signed request, immutable SQLite
|
|
partial proof, definitive `APT_PARTIAL_UNCONFIGURED_VERIFIED` outcome, and closed
|
|
consumed row. `recovery-planning` receives exactly `{native_recovery, proof}`;
|
|
Python rechecks the original still-active witnesses and complete current partial
|
|
snapshot. It seals only the content-addressed baseline and returns the normal
|
|
planning projection plus `native_recovery`. Ordinary planning continues to reject
|
|
unconfigured packages. This passive projection creates no job or authorization.
|
|
|
|
For execution the helper archives the definitive old active directory, stages
|
|
the exact proof as `active/partial-proof.json`, and binds its hash in the new
|
|
signed manifest. Python independently checks history, original target, full
|
|
partial baseline and installed fixture bytes. APT receives only
|
|
`install -- rmm-mvp-test=1.0`; the actual v3 hook must contain exactly one
|
|
equal-version `**CONFIGURE**` action. Unpack, removal, foreign packages and pending
|
|
configuration remain forbidden. The same native sandbox, grant deadlines,
|
|
locked-store handoff and complete postcondition/audit checks apply.
|
|
|
|
Create-once markers are `recovery-attempt-<previous_grant>.json`,
|
|
`pending-recovery-<previous_grant>.json`, and `recovery-<previous_grant>.json`.
|
|
Original/retry markers, signed histories and the original unknown proof remain
|
|
intact. Recovery produces `native_recovery:true`, `recovery_record_sha256` and
|
|
`partial_proof_sha256`; it creates no fresh-install acceptance record or
|
|
`native_record_sha256`. A later separately approved native 1.1 upgrade must
|
|
provide the ordinary acceptance evidence for the changed provider/runtime.
|
|
|
|
Local actual APT 2.6.2, with a vetoing collector and independently guarded fake
|
|
dpkg, emitted only the exact configure action/target; real and copied package
|
|
status stayed unchanged. This is **local regression evidence**, not Cloud-VM
|
|
recovery acceptance. Native deployment, UI approval and execution remain the
|
|
parent's next acceptance step.
|
|
|
|
## Explicit one-attempt recovery (schema 3, 2026-11-13)
|
|
|
|
Schema 2 keeps its exact old encoding (the optional field is omitted). Schema 3
|
|
requires `native_retry` and is valid only for dev-test `apt-native-acceptance`:
|
|
|
|
```
|
|
native_retry: {
|
|
schema_version: 1,
|
|
previous_grant_id: UUID,
|
|
previous_attempt_id: UUID,
|
|
bootstrap_marker_sha256: SHA256(original exact marker bytes)
|
|
}
|
|
```
|
|
|
|
This reference belongs to a **new separately UI-approved signed job**, never
|
|
an unsigned IPC override. Under the existing device lock, before consuming the
|
|
new grant and again before staging, the helper verifies the original saved
|
|
Ed25519 request historically, identical target/generation/assignment/transaction,
|
|
distinct job/attempt/authorization/plan, same-ledger terminal `failed` result
|
|
`HOOK_NOT_HANDED_OFF`, matching recorded outcome, original context/launch/
|
|
sandbox-100 evidence and absent hook/acceptance/retry markers. Historical
|
|
signature verification never grants a current start. Unknown or partial history
|
|
fails closed. Original active state may only move through the existing terminal
|
|
history rule; original tombstone never changes.
|
|
|
|
Provider independently checks original marker hash and immutable history,
|
|
identical full baseline and current normal baseline gates. It exclusively writes
|
|
`bootstrap-retry-<recipe>.json` binding the new attempt, signed reference and
|
|
hashes of historical evidence. Worker, hook and completion recheck it. This is
|
|
one recovery attempt per fixed fixture recipe, not general automatic retries.
|
|
Test/native outcomes are recorded in `docs/implementation-status.md`.
|
|
|
|
**Dedicated-runner update:** the current deployment and readiness protocol is
|
|
defined in [`../../deploy/linux/apt-helper-README.md`](../../deploy/linux/apt-helper-README.md).
|
|
The actual additive domain schema-2 types and AptNativeAcceptance variant have
|
|
since landed and are exercised by a local exact-signature/helper roundtrip test.
|
|
Agent routing and nonce/root-peer/identity/profile/stack-bound readiness are
|
|
implemented. Older descriptions below of absent domain fields or missing runner
|
|
describe the earlier increment, not a remaining implementation gate. Real VM
|
|
profile/probe/installation acceptance remains unmeasured, not passed.
|
|
|
|
## Current integration status / exact outstanding domain change
|
|
|
|
The helper now contains a real provider bridge in
|
|
`crates/privileged-helper/src/apt.rs`, called by its existing peer-credential
|
|
authenticated IPC handler, **not** by a script wrapper. The domain job source
|
|
was leased to the backend worker during this dispatch; it was not edited.
|
|
Legacy package jobs cannot supply the required manifest and remain gated.
|
|
No package capability was added to the agent. No native package/service/reboot
|
|
operation, VM action, helper installation or acceptance record occurred here.
|
|
|
|
Required additive domain/backend contract, before capability advertisement:
|
|
|
|
1. Define typed `AptExecutionManifest` **schema 2**, `ResolvedAptTransaction`
|
|
schema 1 and `PackageArchive` in domain (same exact fields/serde shape as the
|
|
helper types below; do not make domain depend on the helper crate). All deny
|
|
unknown/duplicate fields. No `serde_json::Value` opaque action authorization.
|
|
2. Existing `Action::EnsurePackage` and `Action::ApplyUpdates` gain a field
|
|
`apt_manifest: Option<AptExecutionManifest>`, default None for legacy reads.
|
|
Execution/validation requires Some for APT. Serialization MUST preserve the
|
|
complete object; ignoring unknown fields is explicitly detected and denied by
|
|
`APT_DOMAIN_MANIFEST_NOT_CONFIGURED`. No unsigned IPC manifest field exists.
|
|
3. Add a dedicated Action variant with this exact JSON shape:
|
|
|
|
```json
|
|
{
|
|
"action": "apt_native_acceptance",
|
|
"recipe_id": "rmm-apt-fixture-install-1.0",
|
|
"recipe_version": "1",
|
|
"apt_manifest": {"<all schema-2 fields below>": "<replace this placeholder>"}
|
|
}
|
|
```
|
|
|
|
`Action::name()` and permit.action are `apt_native_acceptance`. Root-only,
|
|
explicit dev-test, specific target, fixed UI-authorized job/attempt. The
|
|
upgrade recipe is `rmm-apt-fixture-update-1.1` and needs another job. This is
|
|
NOT an alias of run_script/diagnostic arbitrary execution. Backend plan/UI
|
|
allowlisting must show full transaction, exact hashes, origin, no-reboot,
|
|
execution identity and test-acceptance nature before approval.
|
|
4. For fixture ensure_package the outer recipe_id/version must match the nested
|
|
transaction exactly as strings. For apply_updates, outer provider=`apt`,
|
|
packages=`["rmm-mvp-test"]`, reboot_policy=`never`, nested upgrade recipe
|
|
only. Other original action parameters are retained and compared against the
|
|
domain's typed serialization, never accepted through parameter aliases.
|
|
5. Backend validation/planning/signing must validate both manifest transaction
|
|
representations, generate JobPayload once and sign its exact payload hash in
|
|
the existing Ed25519 permit. Keep all existing target/tenant/generation,
|
|
authorization/plan/job/attempt/identity/time bindings. Planning needs the
|
|
inspected root runtime/config hashes and immutable baseline/fingerprint.
|
|
6. Agent forwarding/capability negotiation must be separately integrated after
|
|
the domain contract and native prerequisites are complete. This dispatch did
|
|
not change agent/protocol/server files. No optimistic capability claim.
|
|
|
|
Current clear gates include `APT_PROVIDER_NOT_CONFIGURED`,
|
|
`APT_MANIFEST_NOT_CONFIGURED`, `APT_DOMAIN_MANIFEST_NOT_CONFIGURED`; an older
|
|
domain may reject the action even earlier as INVALID_JOB/unknown field. That
|
|
earlier rejection is not a fallback or authorization shortcut.
|
|
|
|
## Public Rust API
|
|
|
|
Current additive passive/no-change contract is documented in
|
|
`deploy/linux/runtime-README.md` ("Passive APT planning and declarative
|
|
no-change"). `readiness::PlanningResult` is returned only by authenticated
|
|
`apt_planning_v1`; it creates no capability. `planning-status` can create only
|
|
content-addressed root metadata seals. A normal exact already-desired fixture
|
|
returns driver `verified_no_change` / `POSTCONDITION_ALREADY_MET`, never a fake
|
|
`POSTCONDITIONS_VERIFIED` transaction/hook. Parent consumption and all signature,
|
|
manifest/runtime/native-record/artifact/current-state gates remain required.
|
|
|
|
```
|
|
apt::ProviderConfig // serde deny_unknown_fields
|
|
apt::AptExecutionManifest // schema 2
|
|
apt::ResolvedAptTransaction // schema 1
|
|
apt::PackageArchive
|
|
apt::is_apt_action(&JobPayload) -> bool
|
|
apt::policy_header(&JobPayload, &ProviderConfig) -> anyhow::Result<()>
|
|
apt::prepare(&Binding, &Request, &ProviderConfig, DateTime<Utc>)
|
|
-> anyhow::Result<PreparedApt>
|
|
PreparedApt::execute(self, &rusqlite::Connection) -> anyhow::Result<Outcome>
|
|
apt::install_known_payloads() -> anyhow::Result<()>
|
|
```
|
|
|
|
PreparedApt has no public fields/unchecked constructor. `prepare` independently
|
|
calls Binding::verify (exact Ed25519 request/grant and all existing bindings),
|
|
checks policy, exact signed manifest/domain preservation/code/runtime bindings,
|
|
installed trusted bytes and pre-grant prefetched artifacts. Parent consumes and
|
|
save_start-persists the request before execute. Execute independently requires
|
|
the corresponding consumed row (same agent/generation/job/attempt, result NULL)
|
|
and the exact originally saved request/signature/permit/plan/authorization.
|
|
Its stable effect_armed_ledger_id is `apt-<grant UUID>-<SQLite rowid>`.
|
|
|
|
## Exact manifest schema 2 inside Action.apt_manifest
|
|
|
|
```
|
|
type: "rmm.apt.helper-action"
|
|
schema_version: 2
|
|
action: "apt-native-acceptance" | "apt-execute"
|
|
execution_profile: "dev-test"
|
|
transaction_sha256: SHA256(transaction_bytes)
|
|
resolved_apt_transaction: complete typed ResolvedAptTransaction object
|
|
transaction_bytes: Vec<u8> / JSON array of integer bytes
|
|
provider_sha256: SHA256(exact installed Python provider bytes)
|
|
hook_sha256: SHA256(exact installed fixed hook bytes)
|
|
apt_config_sha256: SHA256(print-config output bytes)
|
|
runtime_sha256: SHA256(canonical inspect-runtime output object)
|
|
test_result_id: ASCII identifier [A-Za-z0-9_.-], 1..128 bytes
|
|
```
|
|
|
|
The full object AND exact transaction bytes are required. Deserialize the bytes
|
|
with the strict typed schema and require equality to the nested object. The
|
|
provider writes those **same bytes**, not reformatted JSON, to expectation.json.
|
|
It copies **the full original Request.job_bytes unchanged** to signed-action.json;
|
|
job_payload_sha256 in context is SHA256 of those complete domain job bytes.
|
|
The Python loader now requires that full JobPayload envelope and checks the
|
|
nested action, job/attempt/root identity, inner bytes/hash/object and code pins.
|
|
A detached old standalone schema-1 helper-action manifest is no longer accepted.
|
|
|
|
ResolvedAptTransaction fields (all mandatory): schema_version=1, recipe_id,
|
|
recipe_version="1", platform="ubuntu-24.04-amd64",
|
|
resolver_config_version="rmm-apt-local-v1", no_reboot=true, status_fingerprint,
|
|
baseline_sha256, packages. PackageArchive fields: name, architecture,
|
|
old_version (null/string), new_version, origin, sha256, size, archive_path.
|
|
|
|
Only the code-pinned single-package fixture install/upgrade is configured.
|
|
Production and arbitrary catalogs remain denied; a test acceptance does not
|
|
authorize another recipe/closure/profile. Exact fixture hashes are in README.
|
|
|
|
## Root configuration / trusted installation / prefetch
|
|
|
|
Existing root-owned 0600 helper config gains optional `apt_provider` (absent =
|
|
disabled). No new secret/environment variable or caller-supplied path:
|
|
|
|
```json
|
|
{
|
|
"schema_version": 1,
|
|
"execution_profile": "dev-test",
|
|
"allow_fixture_bootstrap": true,
|
|
"allowed_recipes": ["rmm-apt-fixture-install-1.0", "rmm-apt-fixture-update-1.1"],
|
|
"runtime_sha256": "<operator-reviewed canonical runtime hash>",
|
|
"apt_config_sha256": "<operator-reviewed exact config output hash>"
|
|
}
|
|
```
|
|
|
|
These are local policy limits, not approvals. Keep the existing binding,
|
|
signing-key pin, agent UID/socket GID and parent ledger provisioning unchanged.
|
|
No artifact URL/network fetch exists in the root provider.
|
|
|
|
Planned administrator tool installation, **not executed**:
|
|
|
|
```
|
|
/usr/local/libexec/rmm-privileged-helper --install-apt-provider
|
|
```
|
|
|
|
Root-only, fixed paths, create-only: embeds Python/hook bytes at Rust compile
|
|
time, writes root-owned `/usr/lib/rmm-apt-transaction/{apt_transaction.py,hook}`
|
|
(0644/0755), `/var/lib/rmm-apt-transaction` and archives/baselines/history (0700),
|
|
and `install-metadata.json` (0600, provider/hook hashes). Refuses existing files/
|
|
directories instead of replacing/chmodding them. Partial installation requires
|
|
explicit operator reconciliation; no automatic deletion/repair. On each use,
|
|
installed bytes and metadata must match the helper's compiled known payloads.
|
|
The interpreter is fixed `/usr/bin/python3 -I`, root-owned resolved interpreter;
|
|
all provider/store path components are root-owned, nonsymlink and not writable
|
|
by group/others. This installation creates no acceptance or grant.
|
|
|
|
Planned explicit pre-grant fixture preparation, **not executed**:
|
|
|
|
```
|
|
/usr/bin/python3 -I /usr/lib/rmm-apt-transaction/apt_transaction.py provision-fixture-store
|
|
```
|
|
|
|
Only the two pinned deterministic fixture archives can be created, never an
|
|
arbitrary archive/URL. Archives and `prefetch-<sha>.json` receipts are fsynced,
|
|
root-owned 0600, exclusive creation. Receipt fields: schema_version=1, sha256,
|
|
size, sealed_at_ms. Helper requires receipt time <= permit.not_before, matching
|
|
actual SHA256/size/single-link archive. Missing/writable/symlinked/unprefetched
|
|
artifacts fail before consumption. All downloads/imports must finish before the
|
|
final short grant, never during execution. Artifact mTLS fetch elsewhere must
|
|
ultimately yield the same root-verified sealed-store contract, not an agent path.
|
|
|
|
The same preparation stores complete canonical dpkg baseline at
|
|
`baselines/<baseline_sha256>.json` and emits baseline hash/status fingerprint
|
|
for the approved immutable plan. It creates neither jobs nor authorization.
|
|
For subsequent changed baselines, the root-only `prepare-baseline` mode samples
|
|
current dpkg state and creates a new content-addressed canonical baseline before
|
|
the new plan/final grant. An identical existing baseline is only read/verified,
|
|
never rewritten; changed state creates another hash file, never resets archives,
|
|
receipts or acceptance/attempt markers. It creates no job authority. Do not
|
|
modify a sealed file or fake a fingerprint. Archive preparation is create-only.
|
|
|
|
Root `inspect-runtime` / `print-config` provide the planning measurements; hash
|
|
inspect-runtime's canonical JSON object **without its trailing newline**. Review
|
|
the measured binary/OS/dpkg configuration rather than blindly trusting a hash.
|
|
|
|
## Handoff, outcomes, recovery and unit prerequisites
|
|
|
|
Parent handler retains its existing device lock, consumes once, save_start
|
|
persists exact signed request, and rechecks clock/grant before effects. Bridge
|
|
creates active/0700 and expectation/signed-action/baseline/config/context files
|
|
0600 using exclusive nofollow writes and file/directory fsync. Context schema 2
|
|
contains the same grant/job/attempt/authorization/plan IDs and original UTC
|
|
deadline translated to CLOCK_MONOTONIC, not a fresh 60-second grant.
|
|
|
|
An old active directory can only move to history/<old grant UUID> when the same
|
|
parent ledger contains a definitive succeeded/failed result. Unknown/null,
|
|
unrecognized/partial handoffs or existing history destination block execution.
|
|
No tombstone/native bootstrap-attempt record is removed. Parent grant/attempt
|
|
consumption survives any active-directory move.
|
|
|
|
Python receives only fixed mode/path argv and two hash/ledger fields via stdin,
|
|
with cleared environment; no shell, secret argv or script conversion. Structured
|
|
stdout is bounded to 64 KiB (excess drained without unbounded allocation), raw
|
|
stderr discarded. Never timeout-kill APT. Client timeout is unknown while the
|
|
helper keeps running and eventually journals the real result.
|
|
|
|
Exit 0 alone is never success. Strict JSON effect_state/code/evidence validation
|
|
requires bound ledger, exact package versions, full snapshot hash, installed
|
|
fixture payload hash, and bootstrap test flags/native-record/test-result binding.
|
|
Malformed/nonzero/missing/wrong evidence -> unknown. known_failed with an armed
|
|
marker -> unknown, not failed. Existing finish() leaves consumed.result NULL for
|
|
unknown/awaiting_reboot and persists execution_evidence, retaining the device lock.
|
|
|
|
**Existing helper systemd unit is not an APT-capability deployment.** Its
|
|
ProtectSystem=strict/other hardening can prevent the required store/package
|
|
writes and namespace setup. A separately reviewed native runner/unit profile
|
|
must permit the narrowly agreed fixture writes and setup capabilities while
|
|
preserving the provider's final sandbox. No unit sandbox was weakened here.
|
|
Do not announce capability based solely on a successful helper build.
|
|
|
|
Local verification commands/results are reported in the dispatch return.
|
|
Native helper installation, IPC package execution, lock probe, fixture install/
|
|
update and VM approval/acceptance remain unrun. Tests using private temporary
|
|
ledgers/mock children are not native acceptance evidence.
|
|
|
|
Actually executed for this bridge increment:
|
|
|
|
```
|
|
/home/Kevin/.cargo/bin/cargo fmt -p rmm-privileged-helper -- --check
|
|
/home/Kevin/.cargo/bin/cargo clippy -p rmm-privileged-helper --lib --bin rmm-privileged-helper --tests -- -D warnings
|
|
/home/Kevin/.cargo/bin/cargo test -p rmm-privileged-helper --lib --bin rmm-privileged-helper
|
|
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests/apt_transaction -p 'test_*.py' -v
|
|
```
|
|
|
|
Final results: formatting and warning-denying Clippy passed; **16 library + 2
|
|
binary Rust tests passed**, **41 Python tests passed**, AST syntax checks passed
|
|
for **6 Python files**. No full workspace suite was run. An initial Rust test
|
|
fixture used legacy ApplyUpdates, which the current domain rejected as
|
|
`INVALID_JOB`; cryptographic/parent-ledger tests were corrected to use an
|
|
existing valid signed action without executing it or allowing it as an APT
|
|
action. This is not evidence that the missing domain package contract landed.
|