DocsSource

Access control

Access control is computed fresh, per request, from the caller's resolved name — never from a path, and never stored as separate ACL state to persist or rebuild.

Identity: from kernel uid to chat name

Every FUSE request carries the caller's uid, supplied by the kernel — this is the property the whole security model rests on: there is nothing in the request a caller could spoof to pretend to be someone else.

  1. The server resolves that uid to a chat username by looking it up in a cached snapshot of /etc/passwd//etc/group (refreshed at most once per second — matching the kernel's own entry/attr cache TTL, so a burst of lookups from one ls reparses the passwd database at most once).
  2. A user counts as a chat participant only if they are a member — by primary GID or supplementary group membership — of the configured chat group (tbase by default). This is a deliberate enrollment step (usermod -aG tbase wren), not a uid heuristic, so a system or service account is never mistaken for a chat participant.
  3. A uid that doesn't resolve to a group member is never given a real-looking name — it's attributed as the literal string uid:<n> instead, so a non-member can never be misattributed as an actual chat user.
  4. If /etc/passwd//etc/group becomes briefly unreadable (a transient read failure, or a groupdel mid-run), the server falls back to the last good snapshot rather than revoking everyone's access. Only the very first load — with nothing cached yet — propagates the error (which is why the chat group must exist before the server ever mounts: Mount fails fast if it doesn't).

Two channel shapes

  • Public (everyone): every known (group-member) user may see and send.
  • Room (private/<names>): exactly the named users may see and send; everyone else gets ENOENT on lookup — the room doesn't exist for them, it isn't merely access-denied.

Two predicates compute this per request:

  • canSee(channel, caller) — may the caller read/see the channel at all.
  • canSend(channel, caller) — may the caller post/write to it.

For every channel that exists today the two predicates agree exactly. They're kept as separate functions on purpose, so a future read-only membership tier (someone who can see a channel but not post to it) has somewhere to plug in without touching every call site — a couple of media-plane checks already lean on the distinction: a radio/tv listener session is gated on canSee rather than canSend, since tuning in never injects media the way dialing in as a talker does.

Room names

A room name is a comma-separated list of usernames in strictly ascending order, with no duplicates and no empty segments — this guarantees exactly one canonical path per membership set (wren,tomo is not a second name for tomo,wren; it's simply invalid). The two-member case is the ordinary private pair; three or more is a group room, resolved and enforced by the exact same rule.

A room additionally has to name only currently-known users to be reachable — an otherwise well-formed name whose members have left the chat group won't resolve or appear in listings.

The self alias

radio/self/ and tv/self/ are a path alias, not a real directory: they always resolve to whoever is asking, resolved fresh on every single request rather than cached. This spares a broadcaster the redundant ceremony of typing their own username when the server already knows exactly who they are from the authenticated FUSE/SSH connection.

A few things worth knowing about how this is kept safe:

  • The alias is resolved per request, never baked into a node at lookup time. The kernel's normal 1-second directory-entry cache would otherwise let a self dentry cached for one caller get served to a different caller; to prevent that, anything reached through self is additionally given a 1-nanosecond cache lifetime, forcing every traversal back through the server's own per-request resolution regardless of what the kernel might otherwise have cached.
  • A chat user literally named self is not shadowed by the alias: the real-membership check always runs first, so an actual member named self keeps their own correctly-gated slot, and only every other member falls through to the alias.
  • self is never listed by ls radio//ls tv/ — your real name is already always listed there (that's how you find your own slot), so listing the alias too would just show the same slot twice.

See broadcast.md for how the alias interacts with the single-writer session model.

Presence

members reports who is actually reading stream.bot, stream.human, or stream.llm right now — derived directly from live open subscriptions on the channel, with no ping/pong or heartbeat to maintain. The member list (who's allowed at all) comes from the ACL rule above; online/offline status is layered on top from those live handles. The same live-handle-derived pattern is reused elsewhere: file/members reports who currently has file/recv open, and a live call's roster is derived from currently registered voice sessions the same way.