Investigate JWT auth

[lionello]

To prepare agent-box for SaaS, we need to support alternative auth methods (#201). The SaaS portal will likely use OAuth (BetterAuth?) and mint its own JWT instead of the IDP's. How can we seamlessly handover the user's portal session to the user's agent-box(es)?

[defangdevs]

Current auth, for context

The box has no OAuth/OIDC/JWT support today. Caddy gates every route with
basic_auth (bcrypt hash per Linux user, modules/agent-box.nix around
line 18011). A successful basic-auth sets a cookie
(__Host-agent_box_auth_<user>). The cookie is an opaque static secret.
Caddy just string-matches it. There is no signature check and no per-session
expiry — only a 30-day Max-Age.

Caddy here is plain nixpkgs#caddy. No plugin build (no xcaddy, no
caddy-security, no JWT module). Verifying a portal-minted JWT at the edge
would need a custom Caddy build maintained across every deploy flavor this
repo ships (Nix profile, AWS CFN, Lightsail, Azure) — a real infra change,
not a config tweak.

Two designs, real trade-off

A. Verify the JWT at the edge (Caddy).
Build Caddy with a JWT plugin. Give it the portal's JWKS or public key. Caddy
checks signature, exp, and an audience claim naming this box.

• Pro: box stays a pure verifier, no new authenticated code path.
• Con: forces a custom Caddy build + JWKS fetch/refresh (egress from a
  locked-down host) into every deploy flavor. Revocation is hard: a long-lived
  JWT trusted at the edge outlives a portal-side "access revoked" decision
  unless tokens are short-lived and refreshed constantly.

B. Portal-authenticated handoff endpoint, box keeps today's cookie.
Portal redirects the browser to the box with a short-lived, single-use signed
token (JWT or opaque code). A small endpoint in settings-daemon.py verifies
it with PyJWT (already in nixpkgs, no Caddy change) and, on success, sets the
existing __Host-agent_box_auth_<user> cookie itself. Direct basic-auth
login still works as a fallback.

• Pro: no Caddy plugin, no build-pipeline change, works identically on every
  deploy flavor. Portal stays the source of truth for "is access still
  valid" at handoff time, without needing every request re-checked against it.
• Con: adds one more authenticated code path to settings-daemon.py, and the
  one-time token still needs signature+expiry verification somewhere.

Open questions before either design is workable

1. "Agent-box(es)" is plural. A JWT's audience needs to name which box(es)
   it is good for, or the portal needs a per-box key. Worth deciding whether
   the portal signs one JWKS all boxes fetch, or mints a box-specific secret
   at provisioning time.
2. This box is single-owner today (WebPassword = box-owner password, no
   /etc/agent-box/projects.json for a second project — see
   deploy-password-is-root-password.md-shaped gap). A JWT handoff for SaaS
   and a real multi-project auth model are the same problem; solving one
   without the other risks rework.
3. Revocation: today's cookie has no revocation list. If the portal is meant
   to be able to kick a user off their box mid-session (subscription lapses,
   etc.), that argues for short-lived handoff tokens re-checked periodically,
   not a long-lived JWT trusted once at the edge.

Recommendation

Start with B. It needs no Caddy plugin build, so it works unchanged
across the Nix-profile, AWS, Lightsail, and Azure deploy flavors this repo
already supports. It reuses the cookie mechanism already in place. It keeps
the portal as the actual authority (each handoff is a live portal decision,
not a token cached at the edge for its whole lifetime). Design A is worth
revisiting only if the box ever needs to verify access without a portal
round-trip on every login — not the case described in #201/#541.

This is a design decision, not a bug fix, so I'm posting analysis rather
than a PR — happy to prototype B if that's the direction you want to take.