feat(api): a conversation can be shared with a second person, by a token that reaches only it

[brcampidelli]

What

The backend half of multiplayer (item 3 of the list audited on 2026-09-16): a coding conversation can be shared with a second person by a token that opens only that conversation. The owner's decision, 2026-09-17: a token per shared session, never the server token. The screens (Share on the conversation, the guest page, presence and author labels) are the next PR; the two defaults the owner did not rule on are taken as stated — LAN only, opt-in, never open at launch, and guests send messages but do not answer governance cards.

How

chimera/api/sharing.py

• ShareStore — one token per guest (secrets.token_urlsafe(24)), stored in <home>/code_shares.json (same trust boundary as code_sessions/), resolved with a constant-time compare against every stored token, revoked one at a time; deleting a conversation or a project revokes all of theirs.
• SessionBus — every frame a turn emits is also published on the session's bus: numbered by the session (session_seq), enveloped with turn_id and author, kept in a bounded ring (4,000 frames) for replay from since, delivered to subscribers across event loops with call_soon_threadsafe. The browser picture is delivered and not kept, for the run log's reason. Who is subscribed is the presence list; joining and leaving publish a presence frame that is never in the ring (it is about now). A new subscriber's first live frame is the presence list with themselves on it.
• lan_addresses() — the IPv4 addresses a machine on the network could use, without sending a packet.

chimera/api/guest_api.py

• build_guest_app — a separate FastAPI app with four routes, each behind a share token (bearer, or ?t= because EventSource cannot set a header): GET /api/session (the same exchanges the owner's replay shows, with the folder's name and never the owner's path), GET /api/live?since=&name= (replay, then live, heartbeat every 15 s, subscribed for exactly as long as the stream runs), POST /api/turn (runs through the same _start_turn the owner's turn does, on the conversation's own folder, under the request's default seams — the most cautious this surface has — with the guest's name on every frame and on the receipt as author), GET /api/presence. Nothing else answers a share token; there is no route to answer a governance card.
• Mounted under /guest on the owner's server, and the only thing served by GuestServer — a second uvicorn listener on its own thread, bound and listening before it is announced (the lesson of perf(app): the backend listens before it announces its port — a launch stops paying half a second #506), opened by POST /api/code/share/network, closed by DELETE, reported by GET, never open at launch.
• Owner routes: mint (POST /api/code/sessions/{id}/share, with the LAN link only when the door is open — a link that goes nowhere is worse than none), list, revoke one, presence, and GET /api/code/sessions/{id}/live — the owner's own window, which is how the owner's screen will see a turn a guest started.

code_api.py — code_turn now delegates to _start_turn(req, *, author=""); emit publishes to the bus; a turn_started frame carries the message and the author before any work (a viewer who did not send the message needs both to draw the row); the receipt gets author when the turn was not the owner's; _session_view is split from the route so the guest app reads the same fold with the same receipts; deleting a conversation or a project revokes its tokens.

docs/security.md — a section, in ten languages: what a share token opens, what the network door serves, and the sentence that must be said before a link is handed out — a guest can ask the agent to do anything the owner can ask it, in the owner's project, with the owner's tools and spend, short of approving cards.

Tests (11)

Store: mint/resolve/revoke/persist, unreadable file starts empty. Bus: numbering per session, replay from a point, pictures out of the ring, bounded ring, delivery from another thread, presence in and out; live_frames replays, announces the viewer, heartbeats, follows, and leaves the presence when the stream ends. Through the app: readable and writable with the token and with nothing else (no token, wrong bearer, wrong query → 401); the guest's turn lands on this conversation with author: "Ana Lima" on its receipt and the owner's replay shows it; the other conversation is untouched and unnameable; the guest app 404s every owner route (/guest/api/config, /doctor, /code/sessions, /code/approve, /code/share/network, …); the bus carries the guest's turn with the author on every frame, numbered without gaps; deleting the conversation revokes its tokens, one token can be revoked alone, and a token of another conversation cannot be revoked through this one's route; a guest turn runs under the request defaults on the session's own folder with a cleaned, capped name; and the network door opens a real listener on 0.0.0.0:0 that serves /api/session with the token, 401s without it, 404s the owner's routes, is the same door when opened twice, and refuses connections after DELETE.

Sabotage: resolve("") made to return the first share → 4 tests fail; receipt["author"] dropped → the author tests fail; both restored. Full gate on a clean copy in WSL: ruff and mypy clean (363 files), 6561 passed, 18 skipped, 10 xfailed in 191 s. OpenAPI + api-schema.ts regenerated (owner routes; the mounted guest app is outside the main schema by design).

Not in this PR

The screens. A guest name is not authenticated — it is a label the guest gives, shown as given. No rate limit on the guest listener. The share token is stored in clear in the owner's home (stated in the module; it is the same trust boundary as the conversations themselves).

🤖 Generated with Claude Code