feat: preserve failed APT history for one signed UI-approved recovery
Rust development slice / linux (push) Failing after 6s

This commit is contained in:
2026-11-13 15:50:34 +01:00
parent a5c2dce4fb
commit fd7225600b
18 changed files with 1345 additions and 34 deletions
+32
View File
@@ -1,5 +1,37 @@
# Typed RootHelper bridge contract (implementation, not native acceptance)
## 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
+108 -20
View File
@@ -1,7 +1,7 @@
#!/usr/bin/python3
"""Root-helper-only, fail-closed local-archive APT transaction provider.
No network API, resolver approval, grant verifier, or retry mechanism lives here.
No network API, resolver approval, grant verifier, or automatic retry lives here.
See README.md before integrating. Python 3.9+, Linux amd64 only.
"""
import ctypes
@@ -366,12 +366,18 @@ def load_signed_action(transaction, context):
context.action == ('apt-native-acceptance' if outer_action == 'apt_native_acceptance'
else 'apt-execute'), 'DEDICATED_HELPER_ACTION_REQUIRED')
action = job['action'].get('apt_manifest')
exact(action, 'type schema_version action execution_profile transaction_sha256 '
'resolved_apt_transaction provider_sha256 hook_sha256 apt_config_sha256 '
'runtime_sha256 test_result_id transaction_bytes')
manifest_keys = 'type schema_version action execution_profile transaction_sha256 '
manifest_keys += ('resolved_apt_transaction provider_sha256 hook_sha256 apt_config_sha256 '
'runtime_sha256 test_result_id transaction_bytes')
version = action.get('schema_version') if type(action) is dict else None
exact(action, manifest_keys + (' native_retry' if version == 3 else ''))
require(action['type'] == 'rmm.apt.helper-action' and
type(action['schema_version']) is int and action['schema_version'] == 2,
type(version) is int and version in (2, 3),
'SIGNED_ACTION_SCHEMA')
if version == 3:
validate_retry_reference(action['native_retry'])
require(context.action == 'apt-native-acceptance' and context.execution_profile == 'dev-test',
'RETRY_NATIVE_TEST_ONLY')
expected_bytes = sealed_read(ACTIVE / 'expectation.json')
require(type(action['transaction_bytes']) is list and len(action['transaction_bytes']) <= 65536 and
all(type(value) is int and 0 <= value <= 255 for value in action['transaction_bytes']) and
@@ -465,12 +471,95 @@ def runtime_identity():
'unit_profile_sha256': digest(sealed_read(APT_UNIT))}
def check_bootstrap_attempt(transaction, context):
attempt = json_bytes(sealed_read(BASE / ('bootstrap-attempt-' + transaction.recipe_id + '.json')))
require(attempt == {'transaction_sha256': context.transaction_sha256,
'job_payload_sha256': context.job_payload_sha256,
'grant_id': context.grant_id, 'attempt_id': context.attempt_id},
'BOOTSTRAP_ATTEMPT_BINDING')
def attempt_binding(context):
return {'transaction_sha256': context.transaction_sha256,
'job_payload_sha256': context.job_payload_sha256,
'grant_id': context.grant_id, 'attempt_id': context.attempt_id}
def validate_retry_reference(ref):
exact(ref, 'schema_version previous_grant_id previous_attempt_id bootstrap_marker_sha256')
require(type(ref['schema_version']) is int and ref['schema_version'] == 1, 'RETRY_SCHEMA')
for key in ('previous_grant_id', 'previous_attempt_id'):
value = ref[key]
require(type(value) is str and str(uuid.UUID(value)) == value, 'RETRY_ID')
token(ref['bootstrap_marker_sha256'], HASH, 'RETRY_MARKER_HASH')
def historical_retry_evidence(transaction, context, action):
"""Recheck immutable no-handoff evidence, never turn unknown into failed.
The parent separately verifies its signed saved request and definitive
HOOK_NOT_HANDED_OFF result in the SAME consumed ledger before this call.
This evidence check cannot itself authorize a retry: the reference must be
inside the NEW exact signed/UI-approved job payload and consumed attempt.
"""
ref = action['native_retry']
validate_retry_reference(ref)
require(context.action == 'apt-native-acceptance' and context.execution_profile == 'dev-test' and
context.grant_id != ref['previous_grant_id'] and
context.attempt_id != ref['previous_attempt_id'], 'RETRY_NEW_APPROVED_ATTEMPT_REQUIRED')
original_path = BASE / ('bootstrap-attempt-' + transaction.recipe_id + '.json')
original_bytes = sealed_read(original_path)
require(digest(original_bytes) == ref['bootstrap_marker_sha256'], 'RETRY_ORIGINAL_MARKER_HASH')
previous = BASE / 'history' / ref['previous_grant_id']
secure_path(previous, directory=True, private=True)
require(not os.path.lexists(previous / 'hook-armed.json') and
not os.path.lexists(record_path(transaction)) and
not os.path.lexists(BASE / ('pending-acceptance-' + transaction.recipe_id + '.json')),
'RETRY_PRIOR_EFFECT_OR_ACCEPTANCE')
names = ('context.json', 'signed-action.json', 'expectation.json', 'baseline.json',
'launch.json', 'sandbox-result.json')
raw = {name: sealed_read(previous / name) for name in names}
old = VerifiedHelperContext.parse(json_bytes(raw['context.json']))
require(old.action == 'apt-native-acceptance' and old.execution_profile == 'dev-test' and
old.grant_id == ref['previous_grant_id'] and old.attempt_id == ref['previous_attempt_id'] and
json_bytes(original_bytes) == attempt_binding(old), 'RETRY_ORIGINAL_ATTEMPT_BINDING')
require(digest(raw['signed-action.json']) == old.job_payload_sha256 and
digest(raw['expectation.json']) == old.transaction_sha256, 'RETRY_PRIOR_PAYLOAD_HASH')
old_tx = ResolvedAptTransaction.parse(json_bytes(raw['expectation.json']))
require(fixture_scope(old_tx) == fixture_scope(transaction) and
old_tx.status_fingerprint == transaction.status_fingerprint and
old_tx.baseline_sha256 == transaction.baseline_sha256, 'RETRY_BASELINE_OR_RECIPE_CHANGED')
require(digest(canonical(json_bytes(raw['baseline.json']))) == old_tx.baseline_sha256 and
raw['baseline.json'] == sealed_read(ACTIVE / 'baseline.json'), 'RETRY_COMPLETE_BASELINE')
previous_job = json_bytes(raw['signed-action.json'])
current_job = json_bytes(sealed_read(ACTIVE / 'signed-action.json'))
require(all(previous_job[key] == current_job[key] for key in
('tenant_id', 'asset_id', 'agent_id', 'enrollment_generation', 'assignment_version')) and
previous_job['job_id'] == old.job_id and previous_job['attempt_id'] == old.attempt_id and
previous_job['execution_identity'] == 'root' and
previous_job['action']['action'] == 'apt_native_acceptance', 'RETRY_DEVICE_OR_JOB_BINDING')
old_manifest = previous_job['action']['apt_manifest']
require(old_manifest['schema_version'] == 2 and 'native_retry' not in old_manifest and
old_manifest['transaction_sha256'] == old.transaction_sha256 and
bytes(old_manifest['transaction_bytes']) == raw['expectation.json'] and
old_manifest['resolved_apt_transaction'] == json_bytes(raw['expectation.json']),
'RETRY_ORIGINAL_SIGNED_TRANSACTION')
require(json_bytes(raw['launch.json']) == {
'transaction_sha256': old.transaction_sha256,
'effect_armed_ledger_id': old.effect_armed_ledger_id} and
json_bytes(raw['sandbox-result.json']) == {
'transaction_sha256': old.transaction_sha256,
'apt_exit_code': 100, 'reboot_required': False}, 'RETRY_KNOWN_PRE_HOOK_FAILURE_REQUIRED')
require(context.job_id != old.job_id and context.authorization_id != old.authorization_id and
context.plan_sha256 != old.plan_sha256, 'RETRY_NEW_APPROVAL_REQUIRED')
return digest(canonical({name: digest(data) for name, data in raw.items()}))
def bootstrap_binding(transaction, context, action):
binding = attempt_binding(context)
if action.get('native_retry') is not None:
binding.update(native_retry=action['native_retry'], previous_evidence_sha256=
historical_retry_evidence(transaction, context, action))
return BASE / ('bootstrap-retry-' + transaction.recipe_id + '.json'), binding
return BASE / ('bootstrap-attempt-' + transaction.recipe_id + '.json'), binding
def check_bootstrap_attempt(transaction, context, action=None):
action = load_signed_action(transaction, context) if action is None else action
path, binding = bootstrap_binding(transaction, context, action)
require(json_bytes(sealed_read(path)) == binding, 'BOOTSTRAP_ATTEMPT_BINDING')
def invalid_control_syscall_probes():
@@ -549,7 +638,7 @@ def complete_acceptance(transaction, context, action, runtime, evidence):
"""Called only after real child success, armed hook AND independent verify."""
require(context.action == 'apt-native-acceptance' and context.execution_profile == 'dev-test',
'DEDICATED_HELPER_ACTION_REQUIRED')
check_bootstrap_attempt(transaction, context)
check_bootstrap_attempt(transaction, context, action)
prechecks = json_bytes(sealed_read(ACTIVE / 'native-prechecks.json'))
expected_checks = {'namespaces_caps_nnp_seccomp': True, 'readonly_controlpaths': True,
'private_tmpfs_sockets': True,
@@ -881,7 +970,7 @@ def hook():
native_acceptance = context.action == 'apt-native-acceptance'
check_native_gate(transaction, context, action, runtime_identity(), native_acceptance)
if native_acceptance:
check_bootstrap_attempt(transaction, context)
check_bootstrap_attempt(transaction, context, action)
ready = json_bytes(sealed_read(ACTIVE / 'sandbox-ready.json'))
require(ready == {'transaction_sha256': context.transaction_sha256,
'sandbox_version': 1}, 'SANDBOX_HANDSHAKE')
@@ -1087,7 +1176,7 @@ def sandbox_worker():
check_native_gate(transaction, context, action, runtime_identity(),
context.action == 'apt-native-acceptance')
if context.action == 'apt-native-acceptance':
check_bootstrap_attempt(transaction, context)
check_bootstrap_attempt(transaction, context, action)
setup_sandbox()
# Executed natively in the actual mutation sandbox, never synthesized by
# the parent or by a bootstrap flag. Also required for record-backed runs.
@@ -1206,12 +1295,11 @@ def execute(request, native_acceptance=False):
# No reinstall/downgrade/remove is introduced by the no-change path.
check_preconditions(transaction, baseline)
if native_acceptance:
# Persist once per code-defined recipe, independently of active/
# and of grant IDs. Failures are not silently retryable.
durable_once(BASE / ('bootstrap-attempt-' + transaction.recipe_id + '.json'), {
'transaction_sha256': context.transaction_sha256,
'job_payload_sha256': context.job_payload_sha256,
'grant_id': context.grant_id, 'attempt_id': context.attempt_id})
# Original marker never changes. One separately signed retry
# may reference proven no-handoff history; it has its OWN
# create-once tombstone, never a reset of the original attempt.
path, binding = bootstrap_binding(transaction, context, action)
durable_once(path, binding)
durable_once(ACTIVE / 'host-namespaces.json', {
name: os.readlink('/proc/self/ns/' + name) for name in ('pid', 'mnt', 'net')})
durable_once(ACTIVE / 'launch.json', {'transaction_sha256': context.transaction_sha256,