cmux-browser

Source excerpt starting at line 1.

1# Authentication Patterns2 3Login flows, session persistence, OAuth, and 2FA for cmux browser surfaces. Related: [session-management.md](session-management.md), [../SKILL.md](../SKILL.md).4 5Set `SURFACE` from [surface discovery](surface-discovery.md) or from the JSON6returned by `browser open`. Never guess a default surface or log credentials.7 8Saved browser state contains cookies and storage. Use a private directory with9restrictive permissions before saving it:10 11```bash12STATE_DIR="${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}/cmux-browser-state"13umask 07714mkdir -p "$STATE_DIR"15chmod 700 "$STATE_DIR"16STATE_FILE="$STATE_DIR/auth-state.json"17```18 19## Basic login20 21```bash22OPEN_JSON="$(cmux --json browser open https://app.example.com/login --focus false)"23SURFACE="$(printf '%s' "$OPEN_JSON" | jq -r '.surface_ref // .surface_id // empty')"24[ -n "$SURFACE" ] || { printf '%s\n' 'browser open did not return a surface ref' >&2; exit 1; }25cmux browser --surface "$SURFACE" wait --load-state complete --timeout-ms 1500026cmux browser --surface "$SURFACE" snapshot --interactive27cmux browser --surface "$SURFACE" fill e1 "$APP_USERNAME"28cmux browser --surface "$SURFACE" fill e2 "$APP_PASSWORD"29cmux browser --surface "$SURFACE" click e3 --snapshot-after --json30cmux browser --surface "$SURFACE" wait --url-contains "/dashboard" --timeout-ms 2000031```32 33## Saving authentication state34 35```bash36cmux browser --surface "$SURFACE" state save "$STATE_FILE"37chmod 600 "$STATE_FILE"38```39 40State includes cookies, localStorage, sessionStorage, and open tab metadata for that surface.41 42## Restoring authentication43 44```bash45STATE_DIR="${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}/cmux-browser-state"46umask 07747mkdir -p "$STATE_DIR"48chmod 700 "$STATE_DIR"49STATE_FILE="$STATE_DIR/auth-state.json"50OPEN_JSON="$(cmux --json browser open https://app.example.com --focus false)"51SURFACE="$(printf '%s' "$OPEN_JSON" | jq -r '.surface_ref // .surface_id // empty')"52[ -n "$SURFACE" ] || { printf '%s\n' 'browser open did not return a surface ref' >&2; exit 1; }53cmux browser --surface "$SURFACE" state load "$STATE_FILE"54cmux browser --surface "$SURFACE" goto https://app.example.com/dashboard55cmux browser --surface "$SURFACE" snapshot --interactive56```57 58## OAuth / SSO59 60Same shape as basic login, waiting on the provider host and then the return host, with generous timeouts:61 62```bash63OAUTH_STATE_DIR="${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}/cmux-browser-state"64umask 07765mkdir -p "$OAUTH_STATE_DIR"66chmod 700 "$OAUTH_STATE_DIR"67OAUTH_STATE_FILE="$OAUTH_STATE_DIR/oauth-state.json"68OPEN_JSON="$(cmux --json browser open https://app.example.com/auth/provider --focus false)"69SURFACE="$(printf '%s' "$OPEN_JSON" | jq -r '.surface_ref // .surface_id // empty')"70[ -n "$SURFACE" ] || { printf '%s\n' 'browser open did not return a surface ref' >&2; exit 1; }71cmux browser --surface "$SURFACE" wait --url-contains "login.example.com" --timeout-ms 3000072cmux browser --surface "$SURFACE" snapshot --interactive73# fill and click the provider's fields74cmux browser --surface "$SURFACE" wait --url-contains "app.example.com" --timeout-ms 4500075cmux browser --surface "$SURFACE" state save "$OAUTH_STATE_FILE"76chmod 600 "$OAUTH_STATE_FILE"77```78 79## Two-factor80 81Drive the password step, let the user complete 2FA in the webview, then wait with a long timeout (`--url-contains "/dashboard" --timeout-ms 120000`) and save state.82 83## Cookie-based auth84 85```bash86cmux browser --surface "$SURFACE" cookies set session_cookie "$SESSION_COOKIE"87cmux browser --surface "$SURFACE" goto https://app.example.com/dashboard88```89 90## Token refresh91 92Load saved state, navigate, and re-login only when the URL bounced to `/login`:93 94```bash95#!/usr/bin/env bash96set -euo pipefail97STATE_DIR="${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}/cmux-browser-state"98umask 07799mkdir -p "$STATE_DIR"100chmod 700 "$STATE_DIR"101STATE_FILE="${STATE_FILE:-$STATE_DIR/auth-state.json}"102: "${SURFACE:?set SURFACE from browser open or surface discovery}"103 104[ -f "$STATE_FILE" ] && cmux browser --surface "$SURFACE" state load "$STATE_FILE"105cmux browser --surface "$SURFACE" goto https://app.example.com/dashboard106 107if cmux browser --surface "$SURFACE" get url | grep -q '/login'; then108  cmux browser --surface "$SURFACE" snapshot --interactive109  cmux browser --surface "$SURFACE" fill e1 "$APP_USERNAME"110  cmux browser --surface "$SURFACE" fill e2 "$APP_PASSWORD"111  cmux browser --surface "$SURFACE" click e3112  cmux browser --surface "$SURFACE" wait --url-contains "/dashboard" --timeout-ms 20000113  cmux browser --surface "$SURFACE" state save "$STATE_FILE"114  chmod 600 "$STATE_FILE"115fi116```117 118## Security119 120Never commit state files; they contain auth tokens. Take credentials from environment variables. Clear state after sensitive tasks:121 122```bash123cmux browser --surface "$SURFACE" cookies clear --all124STATE_DIR="${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}/cmux-browser-state"125STATE_FILE="${STATE_FILE:-$STATE_DIR/auth-state.json}"126OAUTH_STATE_FILE="${OAUTH_STATE_FILE:-$STATE_DIR/oauth-state.json}"127rm -f "$STATE_FILE"128rm -f "$OAUTH_STATE_FILE"129```130