From 8a5ce08b464df9be3ccbff63e27bfeb38cf9350f Mon Sep 17 00:00:00 2001 From: Ashish Huddar Date: Wed, 20 May 2026 13:03:51 +0530 Subject: [PATCH] Fix remote access review blockers --- docs/mobile-access-v1.html | 691 +++++++++++++++++++++++++++++++++++++ 1 file changed, 691 insertions(+) create mode 100644 docs/mobile-access-v1.html diff --git a/docs/mobile-access-v1.html b/docs/mobile-access-v1.html new file mode 100644 index 000000000..a180eaee6 --- /dev/null +++ b/docs/mobile-access-v1.html @@ -0,0 +1,691 @@ + + + + + + AO Mobile Access V1 Review + + + +
+
+
+
Agent Orchestrator Remote Access
+

Mobile Access V1 Review

+

+ A practical review artifact for the current branch: what V1 ships, why it is enough + for first release, which security concerns are real, and what should move to V2. +

+
+
+ V1 scope + Cloudflare quick tunnel plus Basic Auth and QR entry point. +
+
+ Current status + Good for a pragmatic V1 after proxy-auth and shutdown fixes. +
+
+ Deferred scope + Session cookies, token TTLs, lockouts, and rate limits. +
+
+
+ + +
+ +
+
+ Included +

Remote Dashboard

+

+ The dashboard exposes a desktop Remote button. The tunnel is created only when the + user enables it at runtime; normal ao start remains local-first. +

+
+
+ Included +

Basic Auth

+

+ Public access requires configured credentials. Local loopback dashboard access remains + frictionless unless the request carries a real external proxy address. +

+
+
+ Included +

Terminal Proxy

+

+ Terminal WebSocket traffic routes through the dashboard origin and direct terminal + connections validate the active remote credentials. +

+
+
+ +
+

Runtime Flow

+

+ Remote access is a runtime toggle, not a new startup mode. The happy path is intentionally + short so it works for quick mobile access without VPN setup. +

+
+
+ Step 1 +

Start AO

+

Run AO normally. Dashboard starts local and local access stays easy.

+
+
+ Step 2 +

Click Remote

+

The dashboard calls /api/remote-info to enable remote access.

+
+
+ Step 3 +

Start Tunnel

+

cloudflared is downloaded if needed and starts a quick tunnel.

+
+
+ Step 4 +

Scan QR

+

The modal shows public URL, QR code, username, and password.

+
+
+ Step 5 +

Authenticate

+

Mobile browser opens the public URL and signs in with Basic Auth.

+
+
+
+ +
+
+

V1 Threat Model

+

+ V1 is for a user-controlled development machine and a temporary public tunnel. It is + not a hosted multi-user remote-control service. +

+
    +
  • Public URL is protected with Basic Auth.
    • +
  • Loopback bypass is allowed only for local dashboard use.
    • +
  • External proxy headers with non-loopback addresses require authentication.
    • +
  • Credentials are simple and user-editable for V1.
    • +
+
+
+

Credential Storage

+

+ Credentials are stored in the AO global config. This is a deliberate V1 tradeoff for a + local developer tool, and should be surfaced plainly in the UI. +

+ 
~/.agent-orchestrator/config.yaml
+
+remoteAccess:
+  username: ao
+  password: example-password
+
+
+ +
+

Review Findings Triage

+
+
+
+ Fixed + V1 blocker +
+
+

Cloudflare tunnel auth bypass

+

+ Public tunnel traffic can reach Next through a loopback socket. V1 now avoids + loopback bypass when proxy headers contain an external client address. +

+
+
Keep covered by middleware tests.
+
+ +
+
+ Fixed + Stability +
+
+

Direct terminal shutdown

+

+ Shutdown is now guarded against repeated signal handling and exits cleanly after + the server close callback. +

+
+
Prevents noisy stop behavior.
+
+ +
+
+ Fixed + Compliance +
+
+

Inline platform checks

+

+ web-dir.ts now uses shared platform helpers instead of direct + process.platform checks. +

+
+
Matches AO cross-platform rules.
+
+ +
+
+ Valid + Deferred +
+
+

Plaintext credentials

+

+ Real tradeoff: credentials are stored in local plaintext config. Acceptable for V1, + but the UI should warn users that this is local config storage. +

+
+
Track as V1 UX disclosure or V2 hardening.
+
+ +
+
+ Valid + V2 +
+
+

No rate limiting

+

+ Basic Auth attempts are not rate limited. Generated passwords reduce practical + V1 risk, but V2 should add throttling or lockout behavior. +

+
+
Not a V1 release blocker.
+
+ +
+
+ Accepted + Low +
+
+

Token secret in process env

+

+ AO_REMOTE_WS_TOKEN_SECRET lives in the process environment. That is + acceptable for an ephemeral local process. +

+
+
No V1 action needed.
+
+ +
+
+ Non-issue + Verified +
+
+

atob in middleware

+

+ Next middleware can use atob. Server code uses Buffer + where Node APIs are available. Existing tests cover Basic Auth decoding. +

+
+
No change recommended.
+
+
+
+ +
+
+

V1 vs Stronger Proposal

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CapabilityV1Hardened V2
Login modelBasic AuthToken login plus HttpOnly session cookie
Credential storePlaintext local configHashed/tokenized credential store
Session lifetimeBrowser-managed Basic Auth lifetimeExplicit token TTL and session TTL
Abuse controlsNo rate limitRate limit, lockout, revoke sessions
+
+ +
+

Decision Summary

+

+ V1 is enough if the product goal is temporary mobile access for a local developer: + click Remote, scan QR, authenticate, and control AO from mobile. +

+
    +
  • Do ship as "remote dashboard access through Cloudflare quick tunnel plus Basic Auth."
    • +
  • Do warn that credentials are stored in local plaintext config.
    • +
  • Do not describe V1 as a full mobile-auth platform.
    • +
  • Do move token sessions, lockouts, rate limits, and revocation to V2.
    • +
+
+
+ +
+

Source Files

+
+ 
packages/web/src/middleware.ts
+packages/web/src/middleware.test.ts
+packages/web/server/direct-terminal-ws.ts
+packages/web/server/remote-auth.ts
+ 
packages/web/src/lib/remote-access-manager.ts
+packages/web/src/components/RemoteAccessQR.tsx
+packages/cli/src/lib/web-dir.ts
+docs/mobile-access-v1.md
+
+
+ +

+ Generated as a self-contained review artifact for PR 1901 / Mobile Access V1. +

+
+ +