feat(portal): add the runner-local mobile decision portal and QR pairing

[abrichr]

Implements step 4 of the one-week MVP in .private/MOBILE_ATTENDED_DECISION_PORTAL_2026_07_26.md: Desktop's half of the mobile attended-decision loop — portal lifecycle, customer ingress configuration, one-use QR device pairing, generic OS notifications, and the local task shell.

Desktop owns transport. It adds no decision model: the question, the evidence, the allowed actions, the revalidation, and the outcome all come from openadapt-flow's attended console and are relayed verbatim.

What actually shipped before this PR

I verified the current state across four repos before writing code (per the mid-task correction), reading origin/main directly rather than the stale Desktop checkout.

• Flow already has the decision half on origin/main: console/human_decisions.py (PR #272, #275) projects a signed HumanDecisionTaskV1, and console/app.py serves /api/attention, /api/attention/{run_id}, /api/attention/{run_id}/actions/{action_id}, /api/attention/notification, and /api/runs/{run_id}/artifact.
• Types has the wire contract (openadapt_types/human_decision.py, 0.6.0). This PR does not touch it and does not depend on it — the portal relays Flow's JSON without decoding it, which keeps Desktop out of the concurrent agent's lane.
• Cloud has a responsive dashboard queue and a PHI-free notification outbox, but no QR/device pairing, no PWA/service worker, and no runner-local portal URL anywhere. Its card literally tells the operator to "Open it on the customer runner" — and until now there was nothing on the runner to open.
• Desktop had none of this lane. git grep -i 'portal\|qr\|mobile\|attended' on origin/main returns only unrelated XDG-portal notes; tauri-plugin-notification was registered in src-tauri/src/main.rs:80 and never used.

So the lane was genuinely open, and it is precisely the missing link between Cloud's "go to the runner" and Flow's local evidence.

Pairing security properties, and how each is enforced

All in engine/portal/pairing.py, enforced in the store rather than the UI.

Property	Enforcement
The QR carries no execution capability	The link is {origin}/pair#c={secret} and nothing else. The secret rides in the fragment, which browsers never transmit, so it cannot reach a proxy access log or a referrer header. The phone never receives Flow's console bearer token — it gets a portal session token instead.
Single use, atomically	claim() does find → validate → compare-and-swap under one threading.Lock. A 12-thread barrier test asserts exactly one winner and eleven already_claimed refusals.
Five-minute expiry, server-side	PAIRING_TTL_S = 300 evaluated from time.monotonic() on every access. A test freezes datetime backwards and shows the refusal still fires, so a wall-clock change cannot extend a code and no UI countdown is involved.
Runner-bound	Every record and session carries the runner id and the exact ingress origin it was minted for.
Phishing resistance	Claiming yields a session that is unusable (202 pending_approval) until the operator approves. Both devices display the same six-character code from an alphabet with no 0/O/1/I/L.
No credential at rest in the clear	Only SHA-256 digests are stored; every comparison is hmac.compare_digest. Portal secrets use oapp_, deliberately distinct from Cloud's oap_ local-bridge prefix — a test asserts neither surface's regex accepts the other's secret.
Superseded codes	Showing a new code cancels the previous pending one, so an abandoned QR on a prior screen cannot be scanned later.

Loopback default and ingress opt-in

engine/portal/ingress.py — every widening step is explicit and fails closed:

• Default binds 127.0.0.1 and advertises a loopback URL. reachable_from_phone is False and the pairing screen says so rather than minting a dead link.
• customer_ingress still binds loopback unless you name a specific address; the expected shape is your own reverse proxy beside the runner.
• Refused in every mode: wildcard bind (0.0.0.0, ::, *, empty), plaintext origin, origin with path/query/credentials, hostname-as-bind-address, and customer_ingress without both portal_public_origin and portal_ingress_acknowledged.
• Any invalid combination raises and the portal does not start.

There is no test-only wide bind. tests/test_portal/test_end_to_end.py binds a real socket using the shipped loopback configuration and drives the whole loop over HTTP.

No protected content in notifications

engine/portal/notifications.py is structural, not editorial: it reads one integer from Flow's endpoint and renders the body from a fixed template. No upstream string is ever forwarded, so there is no path by which a question, value, identifier, or application name can reach a lock screen. assert_generic_notification refuses any widened payload, and is called in the portal service, again in the dispatcher before emit, and again in src/lib/attentionNotification.ts before the plugin. Tests feed hostile payloads (MRN 4417092, Coverage: active, the full question text) through every layer and assert they cannot appear.

No service-worker caching of protected routes

engine/portal/shell/sw.js precaches one Object.freezed literal list; there is no after-the-fact cache write; and the fetch handler returns before respondWith for anything not in that list. Because the guard is an allowlist, a newly added protected route is excluded by default. tests/test_portal/test_shell.py parses the worker source and asserts each clause, plus that the precache list contains no /api/ path and is a subset of the server's shell assets. Protected responses are additionally Cache-Control: no-store, no-cache, must-revalidate, private with Pragma: no-cache.

It is a responsive PWA (viewport-fit, safe-area insets, thumb-reachable action bar). No iOS or Android project was added; a test asserts that.

Acceptance tests from the design this satisfies

• an action outside allowed_actions refuses — the shell renders only task.allowed_actions and the relay is a closed route allowlist; Flow remains authoritative
• two operators cannot both decide the same task — one-use claim; concurrent-claim test
• raw evidence responses are no-store, authorization-scoped, and never cached by the PWA/service worker
• no notification contains protected content
• loss of network after tap shows pending/uncertain, never success — the shell shows "Submitted. Waiting for this computer to check the live screen…", relays the runner's exact status, and on 5xx/no-response says the result is uncertain and not to answer again
• an accepted tap is never rendered as verified (test asserts VERIFIED never appears in the shell)

Refusal-matrix cases (expired/forged/wrong-tenant/wrong-pause/wrong-bundle/wrong-event-sequence, idempotency, staleness, uncertain delivery) are Flow's, unchanged and reached through the relay.

What is stubbed, and what must land elsewhere

Nothing in the decision path is stubbed — the seam is real and calls Flow's shipped routes. Two things block end-to-end operation, both outside this diff:

1. Packaging (needs a human). pyproject.toml pins openadapt-flow==1.23.0 in the build extra, which predates console/human_decisions.py (added in 1.24.0), and does not request the console extra — so fastapi/uvicorn are absent from the frozen sidecar and openadapt-flow console exits with an install hint. Freezing uvicorn also needs PyInstaller collection flags in scripts/build_frozen_engine.py. I deliberately did not change the signed-installer runtime pin here: it alters every installer and cannot be validated without the native matrix. The portal works today against a dev install (pip install 'openadapt-flow[console]>=1.24.0').
2. A Flow interface for the console capability. serve() generates its bearer token inside the function and only prints it; there is no injection point. engine/portal/service.py::_parse_console_banner reads the exact banner line with a strict regex that fails loud. A narrow --capability-file option in Flow would replace this properly.

Also worth flagging from the survey: Flow's console middleware refuses any request whose Host is not 127.0.0.1/localhost and any Origin that is not http://127.0.0.1:<port> (console/app.py:89-116). A phone therefore cannot use the console even behind a customer reverse proxy without Host/Origin normalization — which is exactly what engine/portal/flow_client.py does, and why the relay exists rather than a direct proxy.

Gates

• uv run ruff check engine/ tests/ scripts/ — clean
• uv run pytest tests/ — 673 passed, 2 skipped (100 new)
• npm run test:ui — 37 passed (11 new); npm run build — clean
• Wheel build verified to include engine/portal/shell/*; check_release_consistency.py clean; uv lock --check clean
• New dependency segno (BSD-3-Clause, pure Python, no runtime deps) renders the QR locally — a pairing link is never sent anywhere to be encoded

🤖 Generated with Claude Code

https://claude.ai/code/session_01NyCHrzA1psrKMFfroYbzaM

[abrichr]

Update: adversarial security review, and four real defects fixed

I ran an independent adversarial review of this diff against the stated threat model (hostile network, photographed QR, protected evidence must not leak or be cached). It found that several documented properties were not actually enforced. All four are now fixed with regression tests; the review's remaining categories came back clean.

1. The confirmation code defended nothing against the actual threat

The original code was derived from the pairing in create() and then returned to whoever claimed the secret. An attacker who photographs the QR from across the room and claims it first was therefore handed the exact code the operator's screen was displaying — and "approve only if the codes match" would have confirmed the attacker perfectly. approve() took only a pairing_id, so nothing the attacker lacked was ever demanded. The property in the module docstring was simply false.

Fixed by reversing the direction: the code is now minted at claim time, returned only to the claiming device, kept here only as a digest, and the operator types back what their phone is showing. A remote attacker's phone displays a code the operator cannot see, so approval fails. Attempts are bounded (3) and exhausting them cancels the pairing outright. pairing_status() no longer exposes any code.

This deviates from the design doc's literal "matching code on both devices" wording while serving its stated purpose ("reducing remote QR phishing"). It is the numeric-comparison-vs-passkey-entry distinction, and entry is the one that actually resists a copied QR.

2. The five-minute expiry stopped applying once a code was claimed

_expire_locked only expired pending records, and approve() never re-checked the deadline — so a pairing claimed at T+299s could be approved hours later into a full 12-hour session, with pairing_status cheerfully reporting claimed and a clamped 0s. Worse, create() cancelled only pending records, so a stolen-and-claimed code survived the operator displaying a fresh QR and sat latent waiting for a mis-click.

Fixed: claimed records expire too; approve() re-checks the deadline itself and reports expired rather than not_claimed; a new QR retires every unapproved predecessor and revokes its session. Expiry now consults both clocks — monotonic so a wall-clock change cannot extend a deadline, and wall time because CLOCK_MONOTONIC stalls across suspend and a slept laptop would otherwise carry a session well past 12 hours.

3. No socket timeout anywhere — slowloris

_Handler set no timeout, and neither does ThreadingHTTPServer, so socketserver never called settimeout(): every read blocked forever. With daemon_threads = True, a few thousand idle sockets pin every thread and FD. Fixed with an explicit timeout, an explicit protocol_version, a Content-Length parse that refuses instead of raising out of the handler, and an oversized body refused before reading (which also made the previously-dead 413 branches reachable).

4. Console startup could wedge the portal permanently

_start_console called a blocking readline() while holding the service lock, so CONSOLE_START_TIMEOUT_S was decorative — a console that started and printed nothing blocked forever, deadlocking status(), stop(), and every portal_* command with no recovery. stderr was never drained either, so the console would block once its pipe filled. Fixed: startup happens outside the lock, both pipes are drained by reader threads for the process's lifetime, a sentinel fires on early exit so failure is immediate, and terminate() is followed by wait().

Also hardened

• Shell assets are served network-first (cached copy as offline fallback only). Cache-first pinned whatever app.js was installed the first time a phone paired — browsers only reinstall a worker when sw.js itself changes bytes, so a security fix could never have reached an already-paired device. The structural no-post-fetch-write guarantee is unchanged and still asserted.
• The QR is returned as an inert data:image/png URI instead of raw SVG for the Desktop window to inject — it encodes the pairing secret, so a raw-HTML sink there was a secret-exfiltration primitive.
• Only image/png|jpeg|webp are relayed; image/svg+xml is refused as an active document.
• Upstream 5xx bodies are replaced with a fixed message (a traceback or deployment path must not reach a phone); 4xx refusals pass through intact because they are operator-actionable.
• Artifact identifiers reject .., matching what run identifiers already did.
• The relay re-validates run/action identifiers so its boundary cannot drift from the HTTP surface's.
• The evidence blob URL is revoked after load instead of leaking for the document's life.

Review categories that came back clean

Route authorization ordering (no path reaches the relay without an approved session); percent-decoding consistency (the route regexes exclude %, so %2e%2e/%2f 404 rather than bypass); no-store on every protected response including all refusal and 500 paths; CORS (no Access-Control-Allow-Origin is ever emitted, and the credential is an Authorization header with credentials: "omit", so the absence of an origin check on GET is safe); secret handling (log_request and log_error both delegate to the overridden log_message, so there is genuinely no access log — I verified this against the CPython source); eviction flooding (eviction only runs behind a valid secret or an operator action); the claim critical section (genuinely one uninterrupted find → validate → compare-and-swap); and app.js XSS (every interpolation passes through esc(), every attribute is double-quoted, no href/src/on* sink, and CSP has no unsafe-inline).

Gates

686 passed, 2 skipped (113 portal tests), ruff clean, frontend 37 passed + build clean, gitleaks clean, all 14 CI checks green on the previous head.