Design mobile biometric approval for privileged host actions

[8Dionysus]

Context

Agent sessions sometimes reach an operation that currently requires an interactive pkexec/polkit password or local fingerprint confirmation. This belongs at the abyss-machine host boundary because it concerns explicit human authorization for mutating host actions, not agent reasoning or application-level identity.

The desired experience is: an agent proposes a bounded privileged action, the Android phone shows the exact request, the operator confirms with a fingerprint, and the machine executes only the action that was signed.

Core principle

Do not transmit or proxy a fingerprint. Android should create a non-exportable signing key in Android Keystore and require BiometricPrompt before each signature. abyss-machine verifies the signed request envelope.

Proposed shape

Introduce a narrow approval broker / privileged-action gateway owned by abyss-machine.

A request envelope should include at least:

• request_id and one-time nonce
• host identity
• requester/agent and session identity
• normalized action ID and bounded parameters
• human-readable reason
• risk class
• optional changes ledger ID
• creation and expiry timestamps
• digest of the complete canonical request

The phone signs the canonical digest after biometric confirmation. The host verifies pairing, signature, freshness, request binding, and replay state before execution.

Phased integration

Phase 1: allowlisted abyss-machine actions

• Execute only registered action IDs with schema-validated parameters.
• No arbitrary shell strings.
• Reuse existing plan/apply and dry-run-first semantics where available.
• Emit private approval receipts and denial/expiry records under the installed host state root.
• Optionally bind receipts to abyss-machine changes records.

Phase 2: polkit/PAM bridge

• Add a narrowly scoped bridge for selected pkexec/polkit operations.
• Preserve enough action context for the phone to show what is actually being authorized.
• Do not make mobile approval a blanket password replacement for every PAM service.

Security requirements

• fail closed when the phone, broker, verifier, or transport is unavailable
• 15–30 second request TTL by default
• replay protection and one-time consumption
• per-host pairing and revocation
• number matching or equivalent anti-push-fatigue check for high-risk actions
• local Unix socket or loopback binding by default; remote access only through an explicit secure tunnel such as SSH/Tailscale plus authenticated transport
• no biometric templates, passwords, private keys, raw secrets, or live receipts in the public repository
• recovery path through a local password or separate hardware key
• bounded, redacted audit documents

Architecture constraints

• Keep pure request/decision/receipt contracts separate from live Android/network/polkit adapters.
• Treat the Android application as a consumer/signing surface, not as the source of host policy.
• Host policy decides whether an action is eligible for mobile approval before a request is emitted.
• Approval proves human presence for one request; it does not assign workload importance or bypass resource/storage/thermal gates.

Acceptance criteria

• Pure contracts exist for request, decision, signature evidence, expiry, replay, and receipt documents.
• A local verifier can pair a synthetic phone key and validate a signed synthetic request.
• Mutating execution is limited to an explicit action registry with typed parameters.
• Denied, expired, replayed, malformed, and wrong-host requests fail closed.
• Approval receipts can reference an abyss-machine changes ID without leaking private request payloads into Git.
• CLI/status/validate surfaces expose readiness and recent bounded outcomes.
• Public smoke tests cover contract semantics; live tests remain opt-in and synthetic-safe.
• Documentation states the threat model, recovery path, and non-goals.

Non-goals

• forwarding fingerprint data to Linux
• remote unrestricted root shell
• signing arbitrary generated command strings
• silently approving unattended agent actions
• replacing Android lock-screen security or general-purpose account authentication

[8Dionysus]

Related read-only operator surface: #360. The phone may eventually display both pulse state and approval requests, but the telemetry stream and privileged approval path should remain separate trust boundaries.