ai-agent/docs/multi-user.md

# Multi-user — what it would take

Status: **exploration** (2026-10-11). Nothing here is built yet; the open
questions are in the ask-form linked from the conversation that wrote this.

Goal: people other than the owner (Dom, Claire, family…) log into the same
PWA and **chat** — spawn and resume conversations — with access limited to the
projects they've been granted. Today the only way in for a third party is a
mail to `claude@gabvdl.xyz` (the mail-trigger allowlist, guests gated by a
`notify-ask` in `.claude/agents/mail-agent.md`).

## Where the app stands

There is **no notion of a user anywhere**, and that is load-bearing:

| layer | today |
|---|---|
| edge | Authelia forward-auth on `ai-agent.lab.gabvdl.xyz`; the `*.lab` rule admits `gabrielvidal` + `claude` only. Authelia already sends `Remote-User/Groups/Name/Email` — nobody reads them. The host is tailnet/LAN-only (public `*.lab` DNS lands on raspy2, which doesn't route it). |
| API gate | `backend/core/auth.py`: *came from Traefik / loopback / docker gateway* ⇒ **admin**. `READONLY_API_KEY` (the desk phone) is the only downgrade. |
| data | every list (conversations, search index, notifications, forms, plans, projects, dashboards) is global; `ui-state.json` and `notif-read.json` are one shared blob; the SSE hub sends every event to every client. |
| runs | `claude -p --permission-mode bypassPermissions` as uid 1000, cwd = whatever the client sent (only checked to exist), full `os.environ` (incl. `SIDECAR_TOKEN`), user + project hooks/skills/CLAUDE.md, `--remote-control`. A run is a shell on the host. |
| billing | `personal` (the owner's Max seat) by default; no per-run budget, turn cap or spend limit anywhere. |
| notifications | every `notify`/`ask`/`form` goes to the owner's phone through HA webhooks; the PWA does no Web Push. |

So "scope a guest to their projects" is two separate problems:

1. **The API** must know who is calling and filter/deny accordingly.
2. **The run** must not be able to step outside the project — because a guest
   session on today's runner can `curl 127.0.0.1:8096/api/spawn` (trusted
   loopback ⇒ admin), read `~/.claude`, `.env` files and SSH keys, drive the
   sidecar with the inherited `SIDECAR_TOKEN`, or inject turns into the owner's
   live sessions through the inbox sockets (same uid). Backend filtering alone
   is cosmetic until (2) is solved.

## The changes, layer by layer

### 1. Edge — reachability and login

- **Identity**: Authelia users (`services/authelia/config/users.yml`, a
  `guests` group) are the cheapest path — the backend reads `Remote-User` /
  `Remote-Groups` / `Remote-Email`, **only when the TCP peer is Traefik**
  (loopback/gateway callers could forge them). Authelia's notifier is the
  filesystem today, so password reset / TOTP enrolment mails go nowhere — it
  needs SMTP to the mail service before inviting anyone. A built-in login
  (email magic link, passkeys) is the standalone-friendly alternative (GOAL.md
  wants the single container to work without Authelia).
- **Reachability**: guests are not on the tailnet. Options: Tailscale node
  share (shared-in users don't get the tailnet's CoreDNS), publish
  `ai-agent.lab` through the raspy2 passthrough, or a **separate guest host**
  (e.g. `chat.lab.gabvdl.xyz`) that the backend treats as guest-only even for
  the owner — the admin host stays tailnet-only. `auth.lab` must be public too
  for the portal. New `*.lab` hosts need the HTTP-01 cert trick
  (`letsencrypt-http` + `lab-passthrough.sh`). Geo-lock (FR+DE) can sit on the
  raspy2 leg.
- **Authelia rule**: a `domain: <guest host>` rule for `group:guests`
  (`two_factor` for the owner if `ai-agent.lab` itself goes public).
- **Stale bypass**: the `ai-agent-flags` router (`/api/flags`, `api-chain`, no
  Authelia) has no backend route any more; once identity matters, "via Traefik
  with no `Remote-User`" must mean *anonymous ⇒ 401*, and that router should go.

### 2. Backend — identity, grants, enforcement

- **`core/auth.py` → a `Caller`** (`user`, `role: owner|guest|service`,
  `projects`), injected as a FastAPI dependency next to `State`. Mapping:
  Traefik + `Remote-User` ⇒ that user; Traefik without it ⇒ 401; loopback /
  gateway / `INTERNAL_API_TOKEN` ⇒ `service` (= owner, as today); read-only key
  ⇒ owner, read-only; the `claude` Authelia account ⇒ owner (screenshots).
- **Users & grants store** — `/data/users.json`: `{user: {role, email,
  projects: {slug: level}, budget, models}}`, `GET /api/me`, admin CRUD under
  `/api/users` + a Settings → Users page.
- **Route classes** (full table in the exploration notes): admin-only routers
  (`accounts`, `agents`, `cron`, `workers`, `files` editor/bundle, `memories`,
  `templates`, `services`, `settings` hooks/webhooks/mail-trigger, `dashboards`
  context, `project-env`) get an `owner_only` dependency — default-deny, guests
  opt *in* per router. Project-scoped reads filter; code-executing writes
  check.
- **Conversation ownership**: spawn stamps `meta.owner` + `meta.projects` (it
  stamps neither today — `projects` only picks the account). Fork/cron inherit.
  One choke point covers most per-conversation routes
  (`conversations/catalog._resolve_transcript` / `_summary_and_meta`); the
  routes that walk `all_summaries()` (search index, subagents, notifications,
  dashboards) each need the filter, and the derived `homelab` fallback
  attribution must not grant anything.
- **Spawn/resume/fork/interrupt/message for a guest**: the server derives `cwd`
  from a granted slug (never the client's), pins account / worker / harness /
  model to the guest's allowlist, and rebuilds the prompt's guideline block
  server-side (the composer assembles it in the browser today, so a guest could
  write any guideline they like).
- **Forms & asks**: `answeredBy` + an authorization check; a form raised by a
  guest's run is answered by that guest (and/or the owner).
- **Per-user state**: namespace `ui-state` keys by user (split
  `ai-agent-settings` into owner config vs personal prefs), key
  `notif-read.json` by user, tag `uploads/<batch>` with an owner.
- **SSE**: per-subscriber filter in `events.Hub` — `transcript` events carry
  cwd-encoded ids that leak project names and session ids.

### 3. Runner — the real boundary

| option | boundary | cost |
|---|---|---|
| **A. Sandbox container per guest**, paired as a worker | real: only the granted projects mounted, own API key, no host `~/.claude`, no docker socket, egress filtered (block LAN, `:8096`, `:8790`) | needs the in-container runner fixed (see below), a guest worker image, per-guest pairing; deploy/push need a scoped credential or an owner approval |
| B. Host sidecar, CLI-restricted (`--restricted`, tool allowlist, `--setting-sources`, cwd = project) | defence in depth only — same uid, same filesystem; no Bash ⇒ no builds/tests | small |
| C. Host sidecar as a dedicated Unix user | real filesystem boundary | root setup per guest, shared project dirs via groups |
| D. Today's mail-agent model (agent asks the owner first) | prompt-level only — not a boundary | none |

The worker protocol (`worker/`, `backend/workers/`) already gives A most of
its plumbing: the hub pulls (`/feed`, `/outbox`), the worker never calls back,
routing is a field. What's missing is a server-enforced *user → worker*
mapping, one container per guest (runs share the container's uid, so a shared
pool lets guests steer each other), and `/feed` scoped per user.

Whatever the choice, every guest run also needs: no `SIDECAR_TOKEN` in its
env, no `--remote-control` (guest sessions would show up in the owner's
claude.ai list), `--max-budget-usd` / `--max-turns`, and `crossSessionInbound`
off unless the session belongs to the caller.

### 4. Billing & models

Running other people's sessions on the owner's personal Max login spends the
owner's 5 h/weekly limits, and is likely outside what that plan allows (it's a
personal seat). The cleaner options are a dedicated Anthropic API key (Console
spend limit) for the guest runner, the guest's own Claude login inside their
sandbox, or local models through pi (free, weaker; pi only runs on the host
sidecar today). Per-guest caps: `$`/month + a model allowlist.

### 5. Frontend

- `useMe()` → route guards (`<OwnerOnly>` around the admin routes in
  `root.tsx`), nav filtering (`BottomBar` `TABS`, `nav.ts` `SUB_SECTIONS`,
  `Drawer` panels), composer lockdown (account, worker, harness/model, location
  tags, guideline chips, skill/agent mentions, the guidelines master switch).
- Guest pages: home (their waiting forms + their running convs), conversation
  list + thread, granted project pages (without `EnvEditor`).
- Thread: hide account/worker/cron/agent badges, `/plans` `/memories` `/_/`
  links and the account-login fix for guests; cost per turn is a product call.
- Per-user caches: the IndexedDB query cache (`ai-agent-rq-cache`) and the
  RichInput drafts need a user-keyed buster so a shared device doesn't leak.
- Notifications for guests: none today. In-app (SSE + badge) is free; email via
  the mail service is cheap; Web Push needs VAPID + a service-worker handler.

### 6. Mail trigger

The mail-trigger allowlist is the current "guest" list. Natural endpoint:
derive it from the users store (a guest's DKIM-verified mail spawns a
conversation **they** own, in their sandbox, scoped to their projects), and
drop the separate `mail-trigger-senders.json`.

## Findings worth fixing regardless

- **`SIDECAR_TOKEN` is inherited by every run** (`sidecar/claude_accounts.py`
  copies `os.environ`) — any session can drive `/spawn` / `/message` /
  `/interrupt` / account login on the host sidecar directly.
- The host sidecar **binds `0.0.0.0:8790`** (bearer-protected; `/health` open).
- **The in-container runner can't start**: the `Dockerfile` copies 11 sidecar
  modules but not `outbox.py`, `skills_list.py`, `stop_guard.py`, which
  `sidecar.py` / `claude_accounts.py` import — the standalone image
  crash-loops on import when `RUNNER_IN_CONTAINER=1`. `runner/` (pi) and `cli/`
  (notify) aren't in the image either.
- The `ai-agent-flags` Authelia bypass in the homelab shim's `traefik.yml` is
  dead.

## Suggested phasing

1. **Hardening** (no behaviour change for the owner): the four findings above.
2. **Identity + enforcement**: `Caller`, users/grants store, `/api/me`,
   owner-only routers, conversation ownership, per-user state, SSE filtering,
   frontend guards. Shippable dark: with no guest user, nothing changes.
3. **Guest runner**: the sandbox (option A), server-built spawn, budgets.
4. **Edge**: guest host + Authelia rule + SMTP notifier + first invite.
5. **Comfort**: guest notifications, mail-trigger unification, shared threads.