Web-layer auth via Cloudflare Access JWT (MVP, #353)

[woltspace-jerpint]

Closes part of #353 (phase-1 MVP — no admin UI yet, users.json is hand-edited).

Summary

Opt-in per-user permissions on the FastAPI server. Validates the Cloudflare Access JWT that already arrives with every authenticated request, looks up the caller's email in users.json, and gates wolt/app/session routes.

Two modes via WOLTSPACE_AUTH env var:

• none (default): no-op, identical to today's behavior. All existing setups keep working unchanged.
• cloudflare: JWT validated, routes filter + 403 by per-user allow-list.

users.json at wolts/.space/auth/users.json:

{
  "users": [
    {"email": "admin@example.com",        "wolts": ["*"]},
    {"email": "collaborator@example.com", "wolts": ["bloggo"]}
  ]
}

wolts: ["*"] is admin. Admin entry auto-bootstrapped from WOLTSPACE_ADMIN_EMAIL on first boot. Apps inherit access from their keeper wolt (no separate apps list).

Routes gated

• GET /wolts, /sessions, /sites, /apps — filtered to visible
• POST /sessions/new/{create,lodge,telegram,slack} — 403 if target wolt not allowed
• GET/POST /apps/{name}/{detail,start,stop,share,unshare} — 403 if app's keeper wolt not allowed
• GET/POST /sites/{wolt}/{detail,start,stop} — 403 if wolt not allowed
• GET /wolt/{wolt}/site/* — 403 if wolt not allowed
• POST /sessions/{name}/{resume,stop} — 403 if session's wolt not allowed

Out of scope (intentional)

• Admin UI: users.json is hand-edited for the MVP. The lodge UI for user CRUD is the natural next iteration.
• Bot adapters: Telegram/Slack bypass the web tunnel — they keep their existing allow-list mechanisms.
• OS-level isolation: sessions still run as one OS user (node). A running session can still cd ../other-wolt and read files via the shell. Tracked in Phase 2: filesystem-level wolt isolation (follow-up to #353) #354 as a much bigger follow-up.

Implementation

• server/auth.py (new, ~280 lines): JWT validation via PyJWT, users.json CRUD, permission helpers, FastAPI route-guard helpers (require_wolt, require_app).
• server/app.py: middleware to extract email into request.state.user_email, route guards inline.
• test/test_auth.py (new, 26 tests covering both modes).
• HUMANS.md: new "Multi-user permissions" section with the env vars, schema, and a clear scope statement.

Test plan

• uv run --extra test pytest test/test_auth.py -v → 26/26 pass
• Full unit suite (-k "not haiku and not agent_loop and not telegram_loop and not closed_loop and not vulture") → 330/330 pass
• Live test in WOLTSPACE_AUTH=cloudflare mode against a tunnel'd container — set the 3 CF env vars, log in as admin email, confirm /wolts shows everything; log in as a second user, confirm filtered view + 403s on cross-wolt routes
• Live test fallback path with WOLTSPACE_AUTH=none (or unset) — confirm zero behavior change

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
woltspace	Ready	Preview, Comment	Jun 21, 2026 1:15am