Out-of-band approval at the commit gate: host-verified, non-destructive sensitive keys only

[VijitSingh97]

Part of #786 (sub-issue C; decision record in the 2026-08-13 comment there). Post-GA fast-follow — the pre-GA bar is A+B+D.

Goal

The commit gate's flat refusal of non-allowlisted keys becomes a pending, host-verified, out-of-band approval: the dashboard proposes ("change payout wallet to 4A…xyz — approve?"), the operator approves on Telegram, the host verifies, deny-on-timeout, per-operator rate limit. The #338 semantics, extended from its two fixed verbs to gate-refused config commits, reusing its shipped surface (telegram.control.allowed_ids / confirm_timeout).

Hard constraints (unchanged from the decomposition)

1. The host verifies the approval. The shipped ControlGate lives in the dashboard container and is documented as UX, not the boundary — a wallet swap cannot trust a container-relayed "approved". The host runner holds the bot token via config.json and drives its own confirm exchange. This split — container proposes, host independently verifies — has no peer precedent (none of Talos/HAOS/TrueNAS/OPNsense/Synology/UniFi/umbrel run a comparable model). It is the highest-engineering-risk item in the parity roadmap; do not estimate it as "add more keys to Telegram two-way control commands (restart / apply) with access control #338".
2. The never-approve set stays refused even with approval (decision Q2): ssh.enabled/ssh.authorized_key; the approval channel's own identity as a block (telegram.bot_token/chat_id/telegram.control.*); dashboard.control.enabled; the tamper-evidence toggles (telegram.events.wallet_changed, clearnet_exposed); and dashboard.auth.password — it doubles as the root console password every boot, so changing it is root-credential rotation and stays physical-only (D). Peer evidence is convergent: no studied project lets the admin channel's own trust anchor be changed through itself.
3. DEST-flagged destructive changes stay refused in v1 (decision Q5): node local↔remote switches and the Data-dir moves are now dashboard-confirmable but assert_safe_dir is a blocklist, not an allowlist #728 data-dir destination rule are reachable only via D or a local session. No peer extends remote approval to its most destructive actions; TrueNAS instead adds typed re-entry friction locally. A future destructive-ops channel needs its own threat model, not a bundled extension of this one.

v1 approvable set

The non-DEST sensitive keys: wallet addresses, view keys/scan heights, healthchecks.ping_url, notifications.*, stratum password/TLS/bind, node credentials, onion exposure, LAN-access toggles. Config editor surfaces the class as _approval_keys, same pattern as _editable_keys/_confirm_keys.

Known accepted limitation

Telegram is the only approval channel and its identity is in the never-approve set — a lost or rotated bot token disables C until a D (physical) recovery. Same shape as Talos's CA: no revocation list, physical rotation only. Stated here so it is a decision, not a discovery.

Coverage

Tier 1 heavy (the gate is pure shell, the prompt/diff logic pure Python); tier 4 for one live Telegram approval round-trip on the bench.

Dependencies

Nothing in code; operationally requires Telegram already configured — a box without it bootstraps via D, by design.

[VijitSingh97]

Design proposal (2026-08-13) — host-verified approval in the existing vocabulary

Operator direction: "users can update any setting on the fly" from the dashboard. A code-traced design landed out of today's configurability audit; recording it here as the implementation blueprint. Key insight from the trace: the shipped ControlGate confirm loop (telegram_commands.py) runs inside the dashboard container — the code's own comment calls the typed-APPLY confirm "UX friction, not a security control." The approval tier must therefore be verified by the host, and the pieces all exist:

1. A third flag, APPROVE, beside INFO/DEST/CONFIRM in describe_change, for the rows this tier serves: payout wallet addresses, view-key set/change, bind exposures to 0.0.0.0, dashboard.auth user/hash, onion enable, stratum password, notifications.tor. A new CONTROL_DASHBOARD_APPROVE_KEYS allowlist, drift-guarded against a control_service.APPROVE_ENV_KEY_PATHS exactly like the two existing lists, surfaced to the editor as _approve_keys (configlogic gains a third badge: "needs phone approval").
2. The gate calls home itself: where the DEST-refuse block sits today, an APPROVE row triggers control_request_approval — the HOST reads telegram.bot_token/chat_id/control.allowed_ids from its own config.json, POSTs the porcelain diff with an inline Approve/Deny keyboard over the stack's Tor SOCKS (the curl pattern control_upgrade already uses), long-polls for a callback from an allow-listed id matching the request id, bounded by the existing telegram.control.confirm_timeout. Approval touches a .approved marker mirroring the existing .confirmed one; deny-on-timeout refuses. No new mounts, dirs, verbs, or config keys.
3. The never-approve set stays refused forever (unchanged from the decision record above): the Telegram identity/allow-list itself, dashboard.control.enabled, tamper-evidence toggles, ssh.*, workers.list[] descriptors (that's Fleet descriptor editing behind the approval channel #912's own tier), the dashboard password (≡ root console password), and network.tor_egress_firewall. Several are the approval channel's own trust anchor — a channel must never approve changes to itself.

Also landed today, independent of this mechanism: five allowlist reclassifications the audit confirmed as mis-tiered (a missed telegram event toggle, monero.out_peers, proxy.donate_level, the confirm-timeout itself, and the two payout-scan metadata fields to CONFIRM) — those need no approval tier and ship as an ordinary gate-table PR.

Risk note for the implementation: the host-side Telegram round-trip blocks the single-threaded runner for up to the confirm window — same class as the accepted worker-upgrade blocking, but it should decrement a per-drain budget like the other blocking verbs.