RFC: Remote Approval Gate with Zero-Trust Push, In-Flight Steering & Flutter Mobile Companion

[mysma-9403]

Overview & Motivation

In autonomous multi-agent environments (where OpenHuman runs on headless VPS instances, Docker containers, or background desktop daemons), human-in-the-loop (HITL) approval gates are vital for high-risk operations (such as payment checkouts, destructive bash commands, database alterations, or sensitive credential usage).

However, existing desktop-only modal prompts break unattended autonomous workflows whenever the operator is away from their workstation or running a headless server.

We would like to propose and open for discussion an RFC for a Remote Approval Gate with Zero-Trust Push, In-Flight Agent Steering, and a Mobile Companion Client (Flutter), designed strictly around OpenHuman's architectural tenets: zero heavy dependencies, strict privacy / E2E encryption, and lightweight non-blocking asynchronous parking.

This ties directly into the active epic #8369 (tinysecurity policies and approvals migration led by @senamakel), and builds on top of the recent foundation in PR #8452 (feat/remote-approval-steer).

---

1. High-Level Architecture (Zero-Trust Push & Relay)

A major challenge for self-hosted / local-first software is delivering native Push Notifications (FCM / APNs) when the instance sits behind NAT or on a private VPS, without exposing sensitive context to intermediate servers.

sequenceDiagram
    autonumber
    actor Operator as Operator (Mobile Phone)
    participant Core as OpenHuman Rust Core (VPS / Desktop)
    participant Bus as Unified Rust Bus
    participant Relay as Stateless Push Relay (Cloudflare Worker)
    participant FCM as Firebase Cloud Messaging / APNs
    participant Harness as TinyAgents LLM Turn Loop

    Harness->>Core: High-risk Tool Intercept (e.g. shell_exec("git push -f origin main"))
    Core->>Bus: Event: ApprovalRequested (parked on tokio::oneshot)
    Core->>Relay: POST /push (Encrypted Blob + FCM Token)
    Relay->>FCM: Forward opaque encrypted payload
    FCM->>Operator: Native Push Notification with Actions: [Approve, Reject, Steer]

    alt Operator uses Lockscreen Inline Reply: [Steer] -> "Push to fix/login and open PR"
        Operator->>Core: Signed JSON-RPC: approval.steer(request_id, instructions)
        Core->>Bus: Event: ApprovalDecided { decision: "steer", ... }
        Core-->>Harness: GateOutcome::Steer { instructions }
        Harness-->>Harness: Inject Synthetic Tool Return Directive
        Harness->>Harness: LLM adjusts plan immediately in the same turn without context loss
    end

Loading

1.1. Zero-Trust Push Delivery (Two-Tier Model)

1. Default Mode (Zero-Config / Community Relay): A minimal, stateless edge worker (~50 LOC on Cloudflare Workers / Fastly) that receives only an opaque encrypted ciphertext blob + device push token and forwards it to Firebase / APNs. The worker possesses no decryption keys; it is impossible for the relay or FCM to read prompt data, tool arguments, or command summaries.
2. Self-Hosted / BYO Mode: Operators can configure their own FIREBASE_SERVICE_ACCOUNT JSON, ntfy.sh server, or WebPush endpoint directly in config.toml / .env.

1.2. Cryptographic Handshake & QR Pairing

Building upon the foundation in crates/openhuman-core/src/security/devices/:

• Pairing via QR: OpenHuman prints a pairing QR code in the terminal (openhuman pair --qr in ASCII) or desktop UI containing { core_pubkey, channel_id, rpc_url }.
• Key Exchange: X25519 ECDH key exchange establishes a shared secret between the mobile device keychain and the OpenHuman instance.
• Symmetric Cipher: XChaCha20-Poly1305 with random 24-byte nonces and replay sliding windows (TunnelCipher).

---

2. In-Flight Agent Steering (ApprovalDecision::Steer)

Standard approval gates only support binary Approve (execute tool) or Deny (fail turn / error out). The killer capability for autonomous agents is in-flight steering:

• When the operator receives an alert for a risky action, they may want to adjust the command, change parameters, or provide an alternate directive without killing the agent's multi-step plan.
• When approval.steer(request_id, instructions) is invoked, the Rust Core wakes the parked async waiter and passes GateOutcome::Steer { instructions } to the agent harness middleware.
• The harness suppresses execution of the intercepted tool call and returns a synthetic system tool result directly to the LLM:

  [SYSTEM: Tool execution paused by operator. New directive from operator: <instructions>. 
   Do not re-execute the original tool call with the previous parameters. 
   Update your plan and proceed according to the operator's instructions.]
  

• The LLM receives the directive in its turn context and immediately replans its action without losing previous scratchpad thoughts or history.

---

3. Rust Core Architecture (Unified Bus & tinysecurity)

Because OpenHuman can sustain 500+ agents per process, approval parking must never block OS threads or hold database locks:

1. Async Parkers: Requests are parked using tokio::sync::oneshot channels held in an in-memory waiter registry (waiters: Mutex<HashMap<String, oneshot::Sender<GateResolution>>>).
2. Durable Journaling: State is journaled so that if the process restarts or an approval times out, resolution events fire cleanly without dangling state.
3. Strict Privacy Scrubbing: Raw operator steering directives are strictly excluded from structured application logs, error reports, and analytics to comply with privacy rules (AGENTS.md), logging only sanitized metadata such as instructions_len.
4. Wire Endpoints (JSON-RPC):
   • openhuman.approval_list_pending: Enumerate pending gate requests.
   • openhuman.approval_decide: Resolve with standard outcomes (approve_once, approve_always_for_tool, approve_always_for_flow, deny).
   • openhuman.approval_steer: Provide steering instructions (request_id, instructions, agent_id).

---

4. Mobile Companion Client (Flutter Reference Implementation)

Flutter is an ideal cross-platform client (iOS & Android) that interfaces directly with OpenHuman via JSON-RPC over WebSocket or encrypted tunnels:

Key UX Modules:

1. Interactive Push & Lockscreen Inline Reply:
   • Both Android (RemoteInput) and iOS (UNTextInputNotificationAction) support direct inline responses from the lockscreen.
   • The user gets an alert: "Agent coder-01 wants to run git push --force origin main".
   • The user taps [Steer], types: "Push to branch fix/login and open a PR instead", and hits Send.
   • Result: Agent redirection in 3 seconds directly from the notification shade, without needing to open the app!
2. Approval Queue: Swipeable cards with countdown timers (expires_at), risk indicators (Low, Medium, High, Critical), formatted JSON / Bash diffs, and action buttons.
3. Fleet Pulse Dashboard: Real-time stream of active agents, memory consumption, active journals, and quick agent chat.

A full Flutter reference architecture with flutter_local_notifications, firebase_messaging background handlers, and X25519 encryption has been drafted.

---

5. Current Status & Integration Plan

• Rust Core & Web UI Foundation: Initial PR feat(approval): remote approval gate with in-flight steering (#8369) #8452 implements the core ApprovalDecision::Steer engine, harness interception, wire endpoints, privacy log scrubbing, and Web UI approval audit integration.
• Migration Alignment: In line with Epic Tracker: security, policy, approvals and sandboxing onto tinysecurity + tinybox (file-by-file migration epic) #8369, this architecture is structured to cleanly plug into tinysecurity as the unified policy and approval authority.

We would love to hear feedback from @senamakel and the maintainers on:

1. Placement of the stateless push relay worker (whether hosted by the project or maintained as a template in repo).
2. The synthetic tool directive wording and harness contract.
3. Any considerations for the Flutter reference companion client repository structure.

[renezander030]

The lockscreen tap is the last thing the operator sees in this design: once approve_once or approve_always_for_flow resolves, nothing pushes the tool's result back to the device, so a force-push approved from the notification shade lands unseen. I'd send a second encrypted push on completion with the exit status and a revoke for the flow grant, since approve_always_for_flow given one-handed from a lockscreen is the decision most likely to need taking back.

Can a flow grant be revoked from the companion, or only from the desktop?

[mysma-9403]

Both points land, and the answer to the question is worse than the two options you offered: neither. There is no revoke surface at all today — not from a companion, not from the desktop.

What I checked rather than recalled:

• The approval controller exposes exactly list_pending, list_recent_decisions, get_gate_state, decide, steer, preauthorize_flow (crates/openhuman-core/src/security/approval/schemas.rs). Nothing revokes.
• preauthorize_flow is grant-only and idempotent by design — its own description says already-trusted tools are "reported, not re-granted". It cannot be used to withdraw one.
• The operation itself already exists in the store: store_flow_trust::delete_flow_trust(config, flow_id, tool_names: Option<&[String]>) — None drops every grant for the flow, Some(names) revokes just those.
• Its only non-test caller is flows/ops/definitions.rs:243, delete_flow_trust(id, None), as flow-deletion cleanup. So the only way to drop a blanket grant right now is to delete the entire flow.
• No web surface either: grepping app/src for a trust/revoke control finds only URL.revokeObjectURL.

So the gap is one controller over an operation that already exists, and because the companion and the desktop speak the same JSON-RPC, exposing approval.revoke_flow_trust answers both at once. Your framing is the right way round: a grant that cannot be taken back is a worse problem than a missing result push, and approve_always_for_flow from a lockscreen is exactly the one-handed decision that needs an undo.

On the completion push, one correction to the RFC so you are not reviewing something that exists: there is no push path in the code yet at all. Searching the first-party tree for FCM/APNs/WebPush/ntfy/relay returns nothing — the relay and the Flutter client are still proposal, and #8452 lands only the decision/steer engine, the wire endpoints, the log scrubbing and the Web UI audit. A second push on completion is therefore new capability, not a patch to an existing notifier.

The hook you want does exist, with one thing missing. DomainEvent::ToolExecutionCompleted { tool_name, session_id, success, elapsed_ms } (core/events.rs:490) is the natural trigger and already carries success. But it has no request_id or tool_call_id, while ApprovalDecided (core/events.rs:559) carries both. So a completion push keyed to the thing the operator approved from the shade needs that correlation threaded into the completion event; joining on session_id + tool_name is ambiguous as soon as the same tool runs twice in one session, which for git push is not a hypothetical.

I will take both into the RFC: a revoke endpoint over the existing store op, and ToolExecutionCompleted carrying the approval correlation id so a completion notice can name what it is reporting on. Whether that rides in #8452 or a follow-up is a maintainer call — #8452 is already a steering PR and currently has conflicts to resolve against main.

[mysma-9403]

Correcting myself: I answered that from this PR's base, which is 1984 commits behind main, so part of what I told you is already out of date. The question you actually asked still holds, but my "no revoke surface at all" does not.

On current main (after #8487, the security migration):

Whole-tool grants are already revocable from any client, companion included. The approval controller gained two endpoints I did not mention because they do not exist on this branch's base:

• approval.list_tool_trust — "List live durable whole-tool approval grants in the current tenant scope", returning grants with opaque revocation IDs.
• approval.revoke_tool_trust — "Revoke a live whole-tool approval grant by its listed opaque ID."

Both are plain JSON-RPC, so a paired phone can list and revoke approve_always_for_tool today without the desktop.

Flow grants — your actual question — are still not revocable from either client, but the gap is thinner than I made it sound. There is no flow-trust endpoint in schemas.rs on main, so nothing a client can call. One layer down it already exists: ApprovalEngine declares grant_flow_trust, revoke_flow_trust and flow_trust (security/approval/engine.rs:256-273), with the module implementing them. So what is missing is only the controller pair, mirroring list_tool_trust / revoke_tool_trust — not the operation.

And my pointer to the store was wrong. I said "one controller over an existing store op" and named store_flow_trust.rs; that file is gone on main. The grants moved behind the engine seam into TinySecurity, and engine.rs states the split plainly: "the tool and flow grants … are the TinySecurity module's. The gate keeps what is the host's: the verified origin of a call, the approval posture, the legacy import payload, the parked tool-call future, chat routing and the product events." So a flow-trust revoke follows revoke_tool_trust_by_id's shape — engine trait, native impl over the bus, host controller — rather than a host-side SQL delete.

What this does not change: your point stands, and the asymmetry is now the odd part. Whole-tool trust is listable and revocable; flow trust is neither, and approve_always_for_flow is the grant most likely to be given one-handed from a lockscreen. The completion-push point is unaffected — there is still no push path in the tree, and ToolExecutionCompleted still carries no approval correlation id.

Apologies for the stale baseline; I should have checked upstream/main rather than the branch I had checked out, especially when answering "can it be done today".