Module: People
One pane for everyone you know, replacing nine. people.home is a tool
with five sections:
| Section | What it is | Came from |
|---|---|---|
| Friends | The roster, keyed by person; their machines fold underneath | social.friends |
| Messages | Peer chat | network.chat |
| Discover | Username search, and the agent commons directory | commons.directory |
| Requests | The inbound inbox | commons.requests |
| Me | Your username, friend code, devices, profile, diagnostics | commons.profile |
Why nine became one
Five of the retired panes moved whole. The other four —
network.peers, network.monitor, network.lobby, network.relay — were
infrastructure that became destinations: a raw node list, a metrics readout, a
rendezvous client, and a traffic log with two permission toggles. They were panes
because a pane was the only way to show anything.
"Peers" was the clearest case. It answered which machines are connected, when the question a person actually has is which of my friends is around — and it did so in a vocabulary (node ids, transports, trust flags) that means nothing unless you built the fabric. People answers the real question, by person.
Nothing was deleted from the system, only from the list of places to go: transports,
trust and rendezvous remain services (network/ws.ts, lobby.ts, peerchat.ts),
their knobs are on the settings page, and the two diagnostics readouts fold away
under Me rather than each owning a pane.
network, social and commons therefore contribute settings, services and
components, but no panes. That is a legitimate shape for a module here — it is
what "the module registry is the public API" buys you.
Every old name still works
Merging a pane must never reduce reachability, so show("Peers"),
show("social.friends"), show("Commons Requests") and the rest all still resolve,
through VIEW_ALIASES in layout/controller.ts, to the section that holds them
now. A saved layout is disposable and reseeds from its preset; the vocabulary the
user and the agent have learned is not. Pinned by a table-driven test in
layout/__tests__/sections.test.ts.
@username — one name for a person
A human used to have two identities with nothing connecting them:
- a handle on the game server — globally unique, OAuth-derived, shown on the ladder and in HorribleAssault; and
- a
person_idon the peer fabric, rendered as anHD-XXXX-…friend code.
So one screen asked for an "Account ID" while the pane beside it asked for a friend code, and neither could answer "who is this?" about the other's answer. Adding someone meant reading a 25-character code aloud.
The game server is the only uniqueness authority every node agrees on, so the account is the identity. A username is chosen at sign-up and is unique; the server holds one person key per account and signs the certificate of every machine that signs in to it, so all of them are one person. See One account, every machine.
What the two proofs are for
The bearer token proves account; the node signature proves machine. Both are required: without the machine proof, a signed-in user could list someone else's machine under their own username. The signed challenge includes the account id and a timestamp, so it cannot be replayed into another account or reused later.
A handle is a directory name, not an authority
handles.resolve checks that the returned person_id really is the fingerprint of
the key it came with, and each machine's certificate verifies under it. Since the
server holds that key, it vouches for the whole entry; the username is how people
add each other, and trusting the server that issues it is the design.
The presence record published to Atlas carries handle too, and that copy is
a claim, not proof — verify_record checks the record was signed by the person
key it names, which says nothing about who owns the username. Resolve a username
through the game server, never by trusting a presence record.
Search is deliberately narrow
GET /directory/search is prefix, not substring, with a 3-character minimum
and bots excluded. A substring match over a short query is close enough to a scrape,
and LIKE 'q%' can use the handle index while LIKE '%q%' cannot.
LIKE wildcards in a query are escaped, not stripped, and the length gate applies
to the raw query. Stripping them after the check let "%%%" through as an empty
prefix — LIKE '%', i.e. every account in one request. And _ is a legal handle
character, so stripping it would quietly make rob_smith unfindable by anyone who
typed the underscore.
Where @handle is accepted
roster.resolve_target is the shared entry point: @username first (exact and
globally unique), then a friend code or bare person id. It backs add_friend, and
agent_tools.resolve_row adds it to social.message, social.ask_agent and
hassault.invite.
A display name is never accepted by resolve_target — resolving one needs the
roster, and this runs before someone is on it. The agent's resolve_row will try a
display name, but only when it is unambiguous: silently picking the closest fuzzy
match is how an agent messages the wrong person.
friendcode.resolve_person_id stays sync and pure. Its length-based discrimination
is load-bearing, and it deliberately does not fall back to "treat it as a raw
id" when the checksum fails — that fallback would dial a mistyped code as if it
were real.
The duplicated crypto
The game server deploys on its own (Fly) and must not import the node's module
graph, so games_server/crypto.py re-implements two primitives: the person
fingerprint (base32(sha256(pubkey))[:16], lowercase, unpadded — not
base64url) and the Ed25519 verify.
That duplication fails silently and open when it drifts, so it is pinned the way
the Kotlin wire is: backend/tests/test_games_person_binding.py replays both copies
against the node's implementations, and test_games_account_identity.py asserts
the two sides build byte-identical enrollment challenge bytes. The fixture pins agreement; each side's own tests pin correctness.
The Steam shape
The pane got the shape Steam settled on years ago, because it answers the two questions people actually have at a glance: who is around, and is anything waiting for me.
- Friends — you on top, with a status picker (Online / Away / Do Not Disturb
/ Invisible); then a search box and an add-friend button; then the groups
Friend Requests, In-Game, Online, Offline and a folded Sent
Requests, each collapsible. A row is face, name, level, what they're doing
(and for how long), and an unread badge; offline is dimmed rather than hidden.
Right-click a row, or its
⋯, for the app's context menu (Send message / View profile / Machines / Remove / Block). See Status and activity. - Chat dock — clicking a friend opens a chat docked beside the list, one tab per open conversation. In a pane at least 560px wide the two sit side by side; narrower, the chat takes the pane and a back arrow returns to the list.
- Messages — a conversation list with unread badges beside a thread, keyed by person and persisted server-side. See Messages.
- Requests — commons meet requests from strangers, plus a pointer to any friend requests waiting in Friends. See Requests.
- Profiles — clicking a friend's name opens their profile inside the pane: banner, face, status, level, showcases and comment wall, with a Back button.
Faces are decoration, and must be
Avatars and levels come from the game server, fetched once per roster in a single
batched call (profile-cards.ts → POST /api/games/profiles/cards) and cached for
the session. The roster itself is local, so every consumer has to work without a
card: a friend with no username, a signed-out node and an unreachable game server
are all the same case — render the name, the presence dot and an initial, carry on.
The roster must never acquire a network dependency to draw.
Contributions
- Widget:
people.home(tool, 5 sections). OneuseAgentContextprovider, per the sections contract — section bodies render inside this pane's instance id, so two providers would silently overwrite each other. - Commands:
people.open,people.find(jumps to Discover),people.me. - Routes:
POST /api/social/handle/bind,GET /api/social/directory/search. - Game server:
POST /account/devices,GET /directory/resolve,GET /directory/search,POST /directory/people(the reverse lookup: fabric people → their ladder accounts, which a node needs to discover that a friend it already trusts is the same human as an account it already sees),POST /profiles/cards. - Shared pieces:
Avatar.tsx(one face renderer, with the presence dot as a child so it follows the face at any size),profile-cards.ts(the batched cache),conversation.ts(which thread Messages is showing — a store rather than a prop, because the two sides are sibling sections with no parent between them). - Agent tools: unchanged and still
social.*— the pane was renamed, the tool namespace was not. Renaming it would silently re-group the tools (grouping is name-prefix only) and break saved permission rules and Flow graphs at once.
Not done yet
mobile.capture_photo/mobile.notifynow take an optionaldevice, and refuse rather than guess when several phones are connected — but there is still no UI for naming one.- The peer/relay metrics fold away under Me; they are not yet an observability
peerIoSource, which is where they belong. - Own-device presence reads
offlinefor the machine you are sitting at: presence derives from peer-hub sessions, and a node is not a peer of itself.