create-walle 0.9.21 → 0.9.23

package/template/claude-task-manager/docs/microsoft-dev-tunnel-phone-access-design.md

@@ -1,9 +1,10 @@
-# Microsoft Dev Tunnel Phone Access Design
+# Microsoft Dev Tunnel Client Access Design
 
-Status: Implementation update
-Date: 2026-05-19
+Status: Design update
+Date: 2026-05-30
 Owner: CTM / Wall-E
 Related docs:
+- `claude-task-manager/docs/remote-desktop-access-design.md`
 - `claude-task-manager/docs/phone-access-design.md`
 - `claude-task-manager/docs/walle-relay-phone-access-design.md`
 - `claude-task-manager/docs/phone-setup.md`
@@ -12,315 +13,255 @@ External references:
 - Microsoft Dev Tunnels quickstart:
   `https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started`
 - Microsoft Dev Tunnels security:
-  `https://learn.microsoft.com/en-gb/azure/developer/dev-tunnels/security`
+  `https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/security`
 - Microsoft Dev Tunnels CLI reference:
   `https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/cli-commands`
-- VS Code Port Forwarding:
-  `https://code.visualstudio.com/docs/debugtest/port-forwarding`
+- Tailscale quickstart:
+  `https://tailscale.com/docs/how-to/quickstart`
+- Tailscale access controls:
+  `https://tailscale.com/docs/features/access-control/acls`
 
 ## Summary
 
-Microsoft Dev Tunnel is a quick fallback transport for reaching CTM from a
-phone without buying a domain, installing a VPN, or configuring Cloudflare.
-It exposes local CTM through a `*.devtunnels.ms` URL using an outbound host
-connection to Microsoft's Azure-hosted tunnel service.
-
-This is a tunnel, not Walle Remote. It should not replace the Walle Relay
-product direction. It should sit in `Setup -> Access` as a practical fallback:
+Microsoft Dev Tunnel is the default direct browser transport for secure CTM
+access from another browser client, including phone and desktop. CTM supports
+two explicit tunnel access modes:
+
+1. **CTM-authenticated** - recommended for phones. Microsoft Dev Tunnels allows
+   anonymous `connect` to the CTM port, and CTM remains the application auth
+   gate with pairing, client-device token, origin checks, route scopes, passkey
+   step-up, audit, and revocation.
+2. **Private Microsoft gate** - requires Microsoft/GitHub Dev Tunnel browser
+   auth before the request reaches CTM. This is useful when the user wants a
+   provider gate in front of CTM, but it can fail on mobile browsers before CTM
+   can display its pairing UI.
+
+> **Invariant (2026-05-30): CTM-authenticated is the default; private is an
+> explicit opt-in.** Dev Tunnels "private" mode enforces auth by redirecting the
+> *initial request* to an interactive Microsoft/GitHub login page. The phone
+> client is a PWA that reaches CTM via `fetch()` + a `WebSocket` on the same
+> tunnel origin, and programmatic XHR/fetch/WebSocket cannot follow that
+> cross-origin redirect — so forcing private silently bricks remote access
+> ("can't connect / times out"). A brief earlier experiment that made private the
+> default was reverted for this reason. Private is therefore honored only as a
+> deliberate opt-in (an explicit UI selection, `CTM_MS_TUNNEL_ACCESS_MODE=private`,
+> or `options.allowPrivateAccess`); a private value coming only from persisted
+> state is treated as stale and migrated back to CTM-authenticated so the phone
+> keeps working across headless restarts. If you want a true edge sign-in that is
+> compatible with the PWA/WebSocket, use Cloudflare Access (GitHub/Google SSO via
+> a JWT/cookie) or Tailscale (device identity) instead — both are already wired.
+
+The CTM-authenticated flow exposes the local CTM host through a
+Microsoft-managed tunnel like this:
 
 ```text
-iPhone browser
-  -> private devtunnels.ms browser URL
-  -> Microsoft/GitHub Dev Tunnels login gate
+remote browser
+  -> private devtunnels.ms URL
+  -> Dev Tunnels connect-only forwarding
   -> Azure Dev Tunnels service
-  -> devtunnel host process on Mac
+  -> devtunnel host process on the Mac
   -> local CTM on 127.0.0.1:3456
-  -> CTM mobile device claim + optional passkey step-up
+  -> CTM client-device auth, scopes, step-up, audit, and revocation
 ```
 
-The design goal is to make the flow feel like "sign in on the Mac, start
-tunnel, pair phone" rather than "copy terminal commands and hope the URL
-works."
+Anonymous tunnel `connect` is not the same as anonymous CTM access. It only
+lets a browser reach CTM; the CTM app must still reject unpaired devices and
+unauthorized routes. The setup UI must name the selected mode clearly and show
+what is protecting the connection.
+
+This doc covers the transport. The access-control architecture is shared with
+mobile and desktop remote access in `remote-desktop-access-design.md`.
 
 ## Product Positioning
 
-Access methods should be presented in this order:
+Direct browser access methods should be presented in this order:
 
-1. **Walle Remote** - recommended product path, E2E typed relay.
-2. **Microsoft Dev Tunnel** - quick browser fallback, no DNS or VPN.
-3. **Tailscale** - private network fallback.
-4. **Cloudflare Access** - advanced custom-domain fallback.
+1. **Microsoft Dev Tunnel** - default. CTM-authenticated phone-friendly browser
+   tunnel by default, with an optional private Microsoft/GitHub-gated mode.
+2. **Tailscale** - private-network alternative when both devices are in the
+   user's tailnet or the Mac is shared into a tailnet.
+3. **Walle Remote** - typed mobile relay for request/response control when a
+   full browser UI is not required.
 
-Microsoft Dev Tunnel is best when:
+Cloudflare Tunnel is out of scope for the CTM remote-desktop plan and should
+not be shown in the main remote-access setup flow.
 
-- the user wants phone access today;
-- Walle Relay is not deployed yet;
-- the user does not want to install Tailscale on the phone;
-- the user does not own or want to configure a domain;
-- the user is comfortable signing into Microsoft or GitHub on the Mac to manage
-  the tunnel.
+Microsoft Dev Tunnel is best when:
 
-Microsoft's CLI documentation marks Dev Tunnels as preview/no-SLA. Treat this
-as a convenience fallback, not the primary remote-access product contract.
+- the user wants full CTM browser access from another computer or phone;
+- the user wants CTM's own pairing flow to load on the remote browser without
+  first completing Microsoft/GitHub browser auth;
+- the user does not want a VPN or domain;
+- CTM still owns app-level permissions, pairing, passkey step-up, and audit.
 
-It is not best when:
+Tailscale is best when:
 
-- the user requires relay-blind E2E payload privacy;
-- long-running production availability is required;
-- company policy blocks Microsoft Dev Tunnels domains;
-- the user cannot sign into the same Microsoft/GitHub identity on the phone;
-- company policy blocks Microsoft Dev Tunnels domains or browser sign-in.
+- both machines can be authenticated into the same tailnet;
+- the user wants direct private-network access instead of a hosted tunnel;
+- ACLs/grants can restrict CTM to the intended devices and port.
 
 ## Design Principles
 
-1. **Keep the tunnel private.** Microsoft Dev Tunnels are private by default.
-   CTM must not create anonymous `connect` access automatically. The phone
-   signs into Microsoft/GitHub before Dev Tunnels forwards anything to CTM.
-2. **Use CTM auth after the Microsoft gate.** Microsoft/GitHub login decides
-   whether the phone can reach the tunnel. CTM device pairing, scopes, audit,
-   and revocation decide what that browser is allowed to do after it reaches
-   CTM.
-3. **Use a stable tunnel origin.** CTM device cookies and WebAuthn passkeys are
-   origin-scoped. Temporary tunnel URLs create confusing re-pairing failures.
-4. **Make Microsoft gate failures diagnosable.** If Microsoft returns 401 or an
-   auth redirect, the phone request has not reached CTM. In private mode that
-   is expected until the phone signs in with the same tunnel identity.
-5. **Separate tunnel readiness from phone pairing.** A running tunnel only
-   means the network path exists. The phone still needs CTM pairing and local
-   Mac approval.
-6. **Make stop/revoke obvious.** The user should see both controls:
-   `Stop Tunnel` for network exposure and `Revoke Phone` for CTM device access.
-
-## Recommended Flow
+1. **Name the transport gate explicitly.** CTM-authenticated mode lets the
+   browser reach CTM directly and relies on CTM app auth. Private Microsoft
+   gate mode requires Microsoft/GitHub tunnel auth before CTM loads.
+2. **No anonymous CTM access.** CTM-authenticated mode may create a narrow
+   anonymous Dev Tunnel `connect` rule, but CTM must still require pairing,
+   device token, origin checks, route/WS authorization, passkey step-up, audit,
+   and revocation before exposing app data or controls.
+3. **One client-device architecture.** Phone and desktop use the same device
+   identity, pairing, passkey step-up, scopes, audit log, origin binding, and
+   revocation model. The only difference is the UI surface: `/m/` for mobile,
+   `/` for desktop.
+4. **Full desktop means full CTM UI.** A trusted desktop client opens the same
+   dashboard as local use: sessions, terminal, conversation view, prompts,
+   queue, reviews, models, setup, and raw terminal input where permitted.
+5. **No temporary desktop mode.** Do not create a separate reduced desktop
+   product. Use normal CTM with remote auth and policy gates.
+6. **Stable origin required.** CTM cookies and passkeys are origin-scoped.
+   Reuse a persistent tunnel ID and URL instead of temporary URLs.
+7. **Make access failures precise.** Distinguish Microsoft/GitHub auth,
+   tunnel process, CTM origin, CTM device token, route scope, and passkey
+   step-up failures.
+8. **Revocation must close live access.** Revoking a CTM client device closes
+   existing WebSockets and invalidates future HTTP/WS access.
+
+## Recommended Setup Flow
 
 ### Desktop First-Time Setup
 
 1. User opens `Setup -> Access`.
 2. User selects `Microsoft Dev Tunnel`.
-3. CTM shows a four-step setup rail:
+3. CTM shows one setup rail:
 
    ```text
-   1 Install   2 Sign in   3 Start tunnel   4 Pair phone
+   1 Install   2 Sign in   3 Start tunnel   4 Pair browser
    ```
 
-4. CTM checks for `devtunnel` CLI.
-5. If missing, user sees install choices:
-   - `brew install --cask devtunnel`
-   - Microsoft install script / download link
-   - `Refresh`
+4. CTM checks for the `devtunnel` CLI.
+5. If missing, CTM offers install instructions and a refresh action.
 6. CTM checks signed-in status with `devtunnel user show`.
-7. If signed out, user chooses:
-   - `Sign in with Microsoft`
-   - `Sign in with GitHub`
-   - `Use device code`
+7. If signed out, CTM offers Microsoft, GitHub, and device-code sign-in.
 8. CTM creates or reuses a persistent CTM tunnel ID.
 9. CTM creates or verifies port `3456` with protocol `http`.
-10. CTM resets port access to the Dev Tunnels default so stale anonymous access
-    is removed.
+10. User chooses the access mode:
+    - CTM-authenticated: create or verify anonymous `connect` access for this
+      tunnel port and rely on CTM app auth after forwarding.
+    - Private Microsoft gate: verify no anonymous `connect` access exists, and
+      offer `Reset to private` if stale anonymous access is detected.
 11. CTM starts `devtunnel host <tunnel-id>` as a managed child process.
 12. CTM parses the `https://...devtunnels.ms` URL from stdout.
-13. CTM updates the phone origin allowlist for that exact URL.
-14. CTM enables `Pair Phone`.
-15. User clicks `Pair Phone`.
-16. CTM creates a normal CTM device claim using the Dev Tunnel origin.
-17. CTM shows QR, link, account reminder, and local approval expectation.
-
-### Phone First-Time Pairing
-
-1. User scans the QR.
-2. iPhone opens the `https://<tunnel>-3456.<region>.devtunnels.ms/m/claim?...`
-   URL.
-3. Microsoft may show:
-   - anti-phishing interstitial;
-   - Microsoft/GitHub sign-in;
-   - access denied if the phone signs into the wrong account.
-4. After the private gate passes, Microsoft forwards the browser to CTM.
-5. CTM mobile claim page says:
-
-   ```text
-   Microsoft tunnel connected
-   This phone still needs CTM pairing.
-   ```
-
-6. CTM issues a device token for this phone. Passkey registration is used for
-   high-risk step-up, not as the primary proof that the phone can reach CTM.
-7. Mac shows:
-
-   ```text
-   Pair this phone?
-   Account: user@example.com or GitHub username
-   Device: iPhone / Safari
-   Origin: https://<tunnel>-3456.<region>.devtunnels.ms
-   Scopes: Read, Respond
-   ```
-
-9. User approves on Mac.
-10. Phone lands on `/m/`.
+13. CTM updates the origin allowlist for that exact URL.
+14. CTM enables:
+    - `Pair Desktop Browser`
+    - `Pair Phone`
+    - `Copy Desktop URL`
+    - `Copy Mobile URL`
+
+### Remote Browser Pairing
+
+1. User opens the desktop or mobile URL:
+   - desktop: `https://<tunnel>-3456.<region>.devtunnels.ms/`
+   - mobile: `https://<tunnel>-3456.<region>.devtunnels.ms/m/`
+2. In CTM-authenticated mode, the browser should reach CTM directly. In private
+   Microsoft gate mode, Microsoft may show anti-phishing and Microsoft/GitHub
+   sign-in before CTM receives the request.
+3. After the request reaches CTM, CTM shows a pairing gate if the browser has
+   no CTM client-device token.
+4. CTM creates a pending pairing request for the current origin and surface.
+5. The Mac setup page shows the pending request with device hint, origin,
+   requested surface, scopes, and short code.
+6. Local user approves or rejects.
+7. Approval creates a CTM client-device token and registers or verifies a
+   passkey for high-risk step-up.
+8. The browser lands on `/` for desktop or `/m/` for mobile.
 
 ### Returning Use
 
-1. User opens saved CTM mobile URL.
-2. If the tunnel is running and Microsoft browser session is still valid,
-   phone goes straight to CTM.
-3. If Microsoft auth expired, phone signs into Microsoft/GitHub again.
-4. CTM device cookie and passkey remain valid only if the tunnel origin is the
-   same.
+1. User opens the saved URL.
+2. CTM-authenticated mode forwards to CTM directly; private Microsoft gate mode
+   first gates network access with Microsoft/GitHub tunnel auth.
+3. CTM client-device token gates app access in both modes.
+4. If the tunnel origin is stable, CTM cookies and passkeys remain valid.
+5. If CTM token is missing or expired, CTM shows the pairing gate again.
 
 ### Stop and Resume
 
 1. User clicks `Stop Tunnel`.
 2. CTM stops the `devtunnel host` process.
-3. Phone shows `Mac offline` or cannot reach the tunnel URL.
-4. CTM keeps the paired phone record, but the network path is closed.
-5. User clicks `Start Tunnel` later.
+3. Remote browsers can no longer reach CTM.
+4. CTM keeps paired client-device records.
+5. User clicks `Start Tunnel`.
 6. CTM reuses the same persistent tunnel ID and origin.
-7. Phone access resumes without re-pairing.
-
-## Sleep and Idle Availability
-
-Microsoft Dev Tunnel only forwards to CTM while the Mac can run the local CTM
-server and the `devtunnel host` process. If macOS puts the laptop to sleep, the
-phone cannot reconnect until the Mac wakes. Unlocking the laptop often appears
-to "fix" phone access because it wakes the machine and gives the tunnel process
-a chance to reconnect.
-
-CTM should make this contract explicit rather than pretending the tunnel is an
-always-on hosted service.
-
-### Availability Modes
-
-Default mode:
+7. Existing remote browsers resume without re-pairing unless their CTM token or
+   passkey state expired.
 
-- CTM restores a desired-running tunnel at startup.
-- CTM watches for long event-loop gaps that imply sleep/wake.
-- After wake, CTM verifies the managed tunnel process and restarts it if it is
-  missing, stale, or running with an incompatible host-header mode.
-- CTM prefers `--host-header unchanged --origin-header unchanged`, but older
-  Dev Tunnels CLI builds can crash on those flags. When that happens, CTM
-  retries with the default header rewrite mode and relies on forwarded-host
-  recovery in the request/auth layer.
-- The phone app reconnects when Safari returns to the foreground.
+### Expiration And Renewal
 
-Keep-awake mode:
+The `devtunnel` CLI accepts a maximum tunnel/access expiration of 30 days. CTM
+therefore cannot create a never-expiring Microsoft tunnel; it should make the
+remote URL stable by reusing the same tunnel ID and proactively renewing the
+service-side expiration.
 
-- User explicitly enables `Keep Mac awake for phone access`.
-- CTM starts a scoped macOS `caffeinate` process while the Microsoft tunnel is
-  desired-running.
-- The assertion prevents idle system sleep but does not intentionally keep the
-  display awake.
-- The UI shows the active assertion, warns about battery drain, and offers a
-  one-click disable action.
-- CTM stops the assertion when the user disables the mode or stops the tunnel.
+CTM policy:
 
-CTM must not silently prevent sleep forever. The user owns the tradeoff between
-availability and battery/thermal behavior.
+- create persistent tunnels with `--expiration 30d`;
+- renew the tunnel in place with `devtunnel update <tunnel-id> --expiration 30d`;
+- mark renewal due after 25 days, leaving a buffer before the 30-day service
+  limit;
+- for CTM-authenticated mode, recreate the port-level anonymous `connect` access
+  rule on the same 25-day cadence because the CLI exposes `access create` and
+  `access delete`, but not `access update`;
+- keep renewal checks cheap in the normal watchdog path by reading local renewal
+  timestamps first and only calling the CLI when renewal is due, manual setup is
+  run, or access repair is requested.
 
-### Recovery Watchdog
+Renewal does not bypass Microsoft/GitHub account requirements for managing the
+tunnel. If the local `devtunnel` credential expires, CTM should surface a
+sign-in-required state and resume renewal after the user signs in again.
 
-The watchdog should run only when Microsoft tunnel state says
-`desired_running: true`.
+## Tailscale Alternative
 
-On each watchdog tick:
+Tailscale is not anonymous. For the normal case, both sides must be signed into
+the same tailnet. Other secure variants are also possible, such as sharing the
+Mac into another authenticated tailnet user or using managed/auth-key device
+enrollment, but they are still authenticated tailnet flows.
 
-1. Inspect the saved managed tunnel state.
-2. Verify the saved PID still belongs to `devtunnel host <tunnel-id>`.
-3. Confirm the host-header mode is one CTM can authenticate: preferred
-   passthrough flags, or a recorded default-header fallback.
-4. If the process is missing or invalid, call the same restore path used at CTM
-   startup.
-5. If restore succeeds, re-apply the tunnel origin to the in-memory allowed
-   origins.
-6. Persist `last_watchdog_check_at`, `last_watchdog_recovered_at`, and
-   `watchdog_error` for diagnostics.
+CTM should treat Tailscale as a transport, not as the only auth layer:
 
-The watchdog should also detect sleep/wake by measuring timer drift. If a tick
-arrives much later than expected, CTM should run an immediate recovery check
-instead of waiting for a normal polling interval.
+- bind only to loopback and approved private/Tailscale interfaces;
+- rely on Tailscale ACLs/grants to restrict network reachability;
+- still require CTM client-device pairing for `/` and `/m/`;
+- still enforce CTM route/WS scopes and passkey step-up.
 
-### Phone Foreground Reconnect
+## Access Policy
 
-iOS can suspend Safari timers and WebSockets while the phone is idle or in the
-background. The mobile app should reconnect on:
+### Trusted Desktop Client
 
-- `online`
-- `focus`
-- `pageshow`
-- `visibilitychange` when the document becomes visible
+A paired trusted desktop client can:
 
-Foreground recovery should:
+- load the full `/` CTM dashboard;
+- open session tabs;
+- view terminal and conversation history;
+- send raw terminal input to sessions where CTM policy allows it;
+- send Wall-E/coding messages;
+- create sessions and prompts;
+- use queue, review, model, and setup pages subject to scopes and step-up.
 
-1. close any stale WebSocket;
-2. open a fresh WebSocket;
-3. refresh session data immediately;
-4. keep the user's draft text;
-5. show a clear connection state if CTM is unreachable.
+Protected operations still require additional gates:
 
-This does not replace the Mac-side watchdog. It handles the phone-side stale
-browser case after the tunnel is already reachable again.
+- route/WS authorization from `auth-rules`;
+- passkey step-up for high-risk remote actions;
+- local-only restrictions for hooks, telemetry ingest, OAuth callbacks, and
+  other machine-local endpoints;
+- audit events for auth, remote input, model changes, terminal control, and
+  revocation.
 
-### User-Facing States
+### Mobile Client
 
-| State | Meaning | User copy |
-| --- | --- | --- |
-| Tunnel running, keep-awake off | Phone works while Mac stays awake | `Available while this Mac is awake.` |
-| Tunnel running, keep-awake on | CTM is preventing idle sleep | `Keeping this Mac awake for phone access.` |
-| Wake recovery running | CTM detected sleep/wake or stale tunnel | `Recovering the Microsoft tunnel...` |
-| Recovery failed | CTM could not restore the tunnel | `Tunnel recovery failed. Start the tunnel again.` |
-| Phone resumed stale | Safari came back before WebSocket recovered | `Reconnecting to CTM...` |
-
-### Security and Resource Notes
-
-- Keep-awake mode is explicit and reversible.
-- CTM uses `spawn('caffeinate', args)` with fixed argv, not shell strings.
-- No tunnel tokens, Microsoft credentials, or phone pairing secrets are written
-  into power assertion state.
-- Stopping the Microsoft tunnel should also stop the keep-awake assertion.
-- If CTM exits, `caffeinate -w <ctm-pid>` should end with it.
-- Battery users should see a warning before enabling keep-awake mode.
-
-## Critical Origin Decision
-
-Do not use a temporary tunnel as the normal phone setup path.
-
-Temporary hosting is easy:
-
-```bash
-devtunnel host -p 3456
-```
-
-But it creates a new tunnel URL when the host process changes. That breaks
-mobile UX because:
-
-- CTM allowed origins need to change;
-- CTM cookies are scoped to the old origin;
-- WebAuthn/passkey credentials are scoped to the old RP ID;
-- saved home-screen PWA icons point to the old URL;
-- users experience this as "my paired phone stopped working."
-
-Recommended CTM behavior:
-
-```bash
-devtunnel create ctm-<stable-random-id> --expiration 30d
-devtunnel port create ctm-<stable-random-id> -p 3456 --protocol http
-devtunnel host ctm-<stable-random-id> --host-header unchanged --origin-header unchanged
-```
-
-The tunnel ID should be random and non-sensitive. Do not include usernames,
-company names, project names, repo names, or machine names.
-
-If that host command exits immediately with the Dev Tunnels
-`same key ... host` CLI error, CTM retries:
-
-```bash
-devtunnel host ctm-<stable-random-id>
-```
-
-This fallback is acceptable because CTM treats forwarded public tunnel headers
-as the source of truth for origin and WebAuthn recovery when Dev Tunnels rewrites
-`Host` or `Origin` to localhost.
-
-Show the expiry date in the UI. Renew or recreate before expiry if Microsoft
-allows it; otherwise tell the user exactly when re-pairing may be needed.
+A paired mobile client uses the same auth stack, but the `/m/` UI remains
+optimized for phone-sized interaction. Mobile may hide or reshape some controls,
+but that is a UX choice, not a separate auth architecture.
 
 ## Desktop UX
 
@@ -335,22 +276,22 @@ Microsoft Dev Tunnel
 Badge:
 
 ```text
-Quick fallback
+Default secure browser access
 ```
 
 Body:
 
 ```text
-Use a private Microsoft-hosted browser tunnel to open CTM from your phone. No
-DNS or VPN; the phone signs into the same Microsoft/GitHub tunnel account.
+Open CTM from another computer or phone through a private Microsoft Dev Tunnel.
+The remote browser signs into Microsoft/GitHub before CTM loads, then CTM
+pairs and authorizes the browser.
 ```
 
 Security note:
 
 ```text
-This is a tunnel fallback, not Walle Remote. Keep anonymous access off. CTM
-pairing, device permissions, and passkey step-up still apply after the private
-Microsoft gate.
+No anonymous tunnel access. CTM still controls device pairing, permissions,
+passkey step-up, audit, and revocation.
 ```
 
 Primary button by state:
@@ -359,9 +300,11 @@ Primary button by state:
 | --- | --- |
 | CLI missing | `Install CLI` |
 | Signed out | `Sign in` |
-| Ready | `Start Tunnel` |
-| Running | `Pair Phone` |
-| Paired | `Open Phone URL` |
+| Private tunnel ready | `Start Tunnel` |
+| Running | `Pair Browser` |
+| Paired desktop | `Open Desktop URL` |
+| Paired phone | `Open Phone URL` |
+| Anonymous access detected | `Reset to Private` |
 | Error | `Retry` |
 
 Secondary buttons:
@@ -369,195 +312,8 @@ Secondary buttons:
 - `Stop Tunnel`
 - `Refresh`
 - `Diagnostics`
-- `Copy URL`
-
-### Setup Panel Layout
-
-Use one operational panel with a horizontal stepper on desktop and a vertical
-stepper on narrow screens.
-
-```text
-Microsoft Dev Tunnel                         CTM protected
-No DNS or VPN. Phone opens the browser URL, then pairs with CTM.
-
-1 Install ----- 2 Sign in ----- 3 Start tunnel ----- 4 Pair phone
-
-[Current step content]
-
-Connection
-  Account: user@example.com
-  Tunnel: ctm-a8f39c
-  Phone URL: https://ctm-a8f39c-3456.usw2.devtunnels.ms/m/
-  Status: Running
-
-[Pair Phone] [Copy URL] [Stop Tunnel]
-```
-
-Do not bury Cloudflare-style details in form fields. This setup should mostly
-be buttons plus status.
-
-### Step: Install
-
-State copy:
-
-```text
-Install Microsoft's devtunnel CLI once on this Mac.
-```
-
-Actions:
-
-- `Copy Homebrew command`
-- `Open Microsoft install docs`
-- `Refresh`
-
-Detected state:
-
-```text
-devtunnel 1.x detected
-```
-
-### Step: Sign In
-
-State copy:
-
-```text
-Sign into the account your phone will also use.
-```
-
-Controls:
-
-- segmented control: `Microsoft` / `GitHub`
-- `Sign in`
-- `Use device code`
-
-Signed-in state:
-
-```text
-Signed in as user@example.com
-This account manages the tunnel on this Mac only.
-```
-
-### Step: Start Tunnel
-
-Default settings:
-
-- Access: `Private Microsoft/GitHub account access`
-- Tunnel kind: `Persistent`
-- Port: `3456`
-- Protocol: `http`
-- Expiration: `30 days` if supported
-
-Primary CTA:
-
-```text
-Start Tunnel
-```
-
-Running state:
-
-```text
-Tunnel running
-Phone access requires the same Microsoft/GitHub account plus CTM pairing.
-```
-
-Do not offer broad tunnel-level public mode. CTM should reset stale anonymous
-rules back to Microsoft Dev Tunnels defaults rather than creating new anonymous
-rules.
-
-### Step: Pair Phone
-
-Show only after the tunnel is running, the tunnel access is private, and CTM has
-an exact allowed origin.
-
-Content:
-
-```text
-Scan with iPhone. First sign into the tunnel account below if Microsoft asks.
-
-Use this account:
-user@example.com
-
-Then CTM pairs this browser and records its device permissions.
-```
-
-QR payload:
-
-```text
-https://<tunnel>-3456.<region>.devtunnels.ms/m/claim?claim=...&secret=...
-```
-
-Below QR:
-
-- `Copy Link`
-- `Expires in 09:59`
-- `Cancel Claim`
-
-Device list:
-
-```text
-User's iPhone
-Last used 2m ago
-Scopes: Read, Respond
-[Revoke]
-```
-
-## Phone UX
-
-### Before CTM Loads
-
-The user may see Microsoft-owned screens before CTM can render anything. The
-desktop QR panel must set that expectation.
-
-Expected Microsoft screens:
-
-- anti-phishing interstitial;
-- Microsoft/GitHub sign-in;
-- access denied if wrong account.
-
-CTM should not try to style or bypass these screens.
-
-### CTM Claim Page
-
-After Microsoft forwards to CTM, show a compact confirmation:
-
-```text
-Microsoft tunnel connected
-
-Finish pairing this phone with CTM.
-
-Tunnel account: user@example.com
-Mac: User's MacBook
-Access: Read, Respond
-
-[Pair this phone]
-```
-
-If the user is on an unexpected origin:
-
-```text
-This link no longer matches the active Microsoft tunnel.
-Generate a new pairing code on your Mac.
-```
-
-### CTM Home
-
-Once paired, the phone home should include a transport pill:
-
-```text
-Microsoft Tunnel
-Private
-```
-
-Status examples:
-
-- `Connected`
-- `Microsoft sign-in required`
-- `Tunnel stopped`
-- `Mac offline`
-- `Tunnel expires in 3 days`
-
-The transport pill should not dominate the home screen. It is a status signal,
-not the task.
+- `Copy Desktop URL`
+- `Copy Mobile URL`
 
 ## Failure States
 
@@ -565,47 +321,38 @@ not the task.
 | --- | --- | --- |
 | CLI missing | `Microsoft devtunnel CLI is not installed.` | Install, then refresh |
 | Auth missing | `Sign into Microsoft or GitHub before starting a tunnel.` | Sign in / device code |
-| Microsoft sign-in required | `Microsoft is asking the phone to sign in before CTM can load.` | Sign in on the phone with the account shown on the Mac |
-| Anonymous access found | `This tunnel has public browser access enabled.` | CTM resets the port access to private before showing Ready |
+| Provider sign-in required | `Sign into the private Microsoft tunnel before CTM can load.` | Complete provider sign-in |
+| Anonymous access detected | `This tunnel allows anonymous browser access. Reset it to private before using CTM remote access.` | Reset to private |
 | Tunnel start failed | `Tunnel did not start.` | Retry, copy diagnostics |
-| Temporary URL changed | `This phone link belongs to an old tunnel.` | Reuse persistent tunnel or re-pair |
+| Temporary URL changed | `This browser link belongs to an old tunnel.` | Reuse persistent tunnel or re-pair |
 | Origin not allowed | `CTM has not trusted this tunnel URL yet.` | Refresh setup, save origin |
+| CTM device missing | `Pair this browser before using CTM remotely.` | Approve pairing on Mac |
 | Claim expired | `Pairing code expired.` | Generate a new code |
-| Microsoft service blocked | `This network blocks Microsoft Dev Tunnels.` | Use Walle Remote, Tailscale, or Cloudflare |
+| Microsoft service blocked | `This network blocks Microsoft Dev Tunnels.` | Use Tailscale |
 | Tunnel stopped | `Microsoft tunnel is stopped.` | Start tunnel on Mac |
 | Tunnel expiring | `Tunnel expires soon.` | Renew or recreate before expiry |
 
 ## Security Posture
 
-### Required
-
-- Microsoft/GitHub account required on the Mac for tunnel management.
-- The phone must pass the Microsoft/GitHub private tunnel gate before CTM sees
-  the request.
-- CTM device claim is still required so CTM can name, scope, revoke, and audit
-  the browser/device.
-- Local Mac approval required for first phone pairing.
-- CTM route authorization registry still applies.
-- High-risk CTM actions still require passkey step-up when the browser has a
-  CTM passkey registered for this origin.
-- Anonymous access is disabled by default and should not be created by CTM.
-- No tunnel access tokens in QR codes.
-- No inspect URL shown in the primary UI.
-
-### Important Caveat
-
-Microsoft Dev Tunnel does not provide Walle-style relay-blind payload privacy.
-For web forwarding, Microsoft terminates TLS at the tunnel service ingress and
-rewrites headers for development scenarios. Treat Microsoft as part of the
-trusted transport path.
-
-That is acceptable for a fallback tunnel if:
-
-- the Microsoft/GitHub private gate remains on;
-- CTM app-layer auth remains strong;
-- the user understands that Dev Tunnels is a Microsoft-hosted relay, not an E2E
-  blind relay;
-- sensitive long-running remote access moves to Walle Remote once available.
+Required:
+
+- Microsoft/GitHub account required for Dev Tunnel management and remote
+  browser access.
+- No anonymous CTM app access. CTM-authenticated mode may use a connect-only
+  anonymous Dev Tunnel rule, but CTM pairing, device token, route scopes, and
+  passkey step-up remain mandatory app gates.
+- CTM client-device token required for app access.
+- Local Mac approval required for first browser pairing.
+- CTM route authorization registry applies to HTTP and WebSocket actions.
+- High-risk remote actions require passkey step-up.
+- No tunnel access tokens in QR codes or browser URLs.
+- Revocation closes active WebSockets and blocks future HTTP/WS requests.
+- Audit records include transport, origin, surface, device, scope, and action.
+
+Microsoft Dev Tunnel does not provide relay-blind payload privacy. Microsoft is
+part of the trusted transport path. That is acceptable for this product shape
+because the user explicitly selected Microsoft as the default secure transport
+and CTM still owns app-layer authorization.
 
 ## Implementation Notes
 
@@ -618,26 +365,28 @@ Store:
 - port;
 - protocol;
 - signed-in account display;
-- private access status and whether stale anonymous access was removed;
+- private access status;
+- anonymous-access drift status;
 - expiration timestamp if available;
 - managed process PID;
 - last stdout/stderr lines for diagnostics;
-- whether CTM allowed origin has been applied.
+- exact CTM allowed origin;
+- paired client-device IDs for desktop and mobile surfaces.
 
 Do not store Microsoft/GitHub passwords or login tokens. The `devtunnel` CLI
 uses the system credential store.
 
 ### Process Management
 
-CTM should manage `devtunnel host <tunnel-id>` as a child process, similar to
-the Cloudflare fallback process model:
+CTM should manage `devtunnel host <tunnel-id>` as a child process:
 
 - start with fixed argv, not shell strings;
 - capture stdout and stderr;
 - parse the public URL;
 - detect exit;
 - expose `Stop Tunnel`;
-- do not restart CTM unless the local CTM bind/origin config requires it.
+- restore desired-running tunnel state after CTM restart or Mac wake;
+- do not restart CTM unless local bind/origin config requires it.
 
 ### Readiness
 
@@ -647,23 +396,13 @@ the Cloudflare fallback process model:
 - user signed in;
 - persistent tunnel exists;
 - port `3456` configured;
-- stale anonymous browser `connect` access is absent;
+- tunnel access is private;
+- no anonymous connect access is detected;
 - host process running;
 - CTM allowed origin includes the tunnel URL;
-- CTM device claim can be generated for that origin.
+- CTM client-device pairing can be generated for that origin.
 
-Do not show QR before these checks pass.
-
-## Accessibility and Responsive Design
-
-- Stepper labels must be text, not color-only state.
-- All buttons must be at least 44px tall.
-- QR must have a copyable link and short-code fallback.
-- Status updates should use `aria-live="polite"`.
-- The account reminder must be visible near the QR on desktop and phone-sized
-  setup screens.
-- Error copy should state whether the problem is Microsoft auth, tunnel
-  process, CTM origin, or CTM pairing.
+Do not show remote URLs before these checks pass.
 
 ## Test Plan
 
@@ -671,23 +410,38 @@ Manual happy path:
 
 1. Install `devtunnel`.
 2. Sign into Microsoft or GitHub.
-3. Start persistent tunnel.
-4. Confirm CTM shows a `devtunnels.ms` phone URL.
-5. Scan QR on iPhone.
-6. Complete CTM passkey pairing.
-7. Send a low-risk session message.
-8. Stop tunnel and confirm phone loses access.
-9. Start tunnel again and confirm phone does not need re-pairing.
+3. Start persistent private tunnel.
+4. Confirm CTM shows both desktop and mobile URLs.
+5. Open desktop URL from another browser/computer.
+6. Complete Microsoft/GitHub tunnel auth if prompted.
+7. Approve CTM browser pairing on the Mac.
+8. Open a session and send a low-risk terminal/message action.
+9. Open mobile URL and confirm the same auth architecture with `/m/`.
+10. Stop tunnel and confirm remote clients lose access.
+11. Start tunnel again and confirm clients resume without re-pairing.
+12. Revoke the remote browser and confirm existing WebSocket closes.
 
 Negative cases:
 
+- anonymous tunnel access detected;
 - expired claim;
 - tunnel host process crash;
 - tunnel URL changes;
 - CTM allowed origin missing;
-- stale anonymous access left by an older CTM build;
+- provider sign-in appears before CTM;
+- CTM device token missing;
 - high-risk action without CTM step-up.
 
+Automated coverage should include:
+
+- tunnel state normalization;
+- anonymous-access drift detection;
+- origin allowlist generation;
+- pairing request lifecycle for desktop and mobile surfaces;
+- HTTP route auth regression;
+- WebSocket auth and revoke-close regression;
+- audit event shape for remote desktop and mobile.
+
 ## MVP Cut Line
 
 MVP includes:
@@ -695,26 +449,27 @@ MVP includes:
 - setup card and stepper;
 - CLI detection;
 - sign-in status and account display;
-- persistent tunnel create/reuse;
-- private access reset/check so stale anonymous browser access is removed;
+- persistent private tunnel create/reuse;
+- anonymous-access drift detection and reset action;
 - managed `devtunnel host` process;
 - exact origin allowlist;
-- phone pairing QR;
+- desktop and mobile pairing links;
+- shared client-device auth for `/` and `/m/`;
 - stop tunnel;
 - diagnostics copy.
 
 MVP excludes:
 
-- anonymous browser access;
+- Cloudflare Tunnel;
+- anonymous tunnel access;
+- separate temporary desktop mode;
 - team/tenant/org access controls;
-- tunnel access tokens for phone;
-- traffic inspection UI;
-- automatic public beta positioning as primary access.
+- tunnel access tokens in browser URLs;
+- traffic inspection UI.
 
 ## Recommendation
 
-Build Microsoft Dev Tunnel as a polished fallback because it removes most of
-the Cloudflare setup burden. Do not position it as the primary Walle Remote
-solution. The UI should be honest: it is fast and browser-only, but it is still
-a Microsoft-hosted private browser tunnel plus CTM device auth, not an E2E
-typed relay.
+Use Microsoft Dev Tunnel as the default direct browser remote-access option.
+Use Tailscale as the private-network alternative. Keep Walle Remote for typed
+mobile relay workflows. Do not add Cloudflare Tunnel or a separate temporary
+desktop mode to this plan.