Skip to content

A person invites another into a session by name, to observe or control: a pod session's invitation is its grant made visible, a private session's key goes from its owner's daemon into the invitee's own slot at the key manager, which the plane holds the path of and cannot read, taking one back re-keys the session forward, and everybody present is named

Decision 949 · accepted · 2026-10-25 · issue #765

Superseded in part

In part by 952.

765, the maintainer's call of 2026-10-25: "by name, observe or control; a pod session's

invite is the grant made visible; a private session's key is wrapped into the invitee's own OpenBao slot; revoke re-keys forward."

A pod session

The invitation is the grant made visible. session.invite {session_id, subject, role} by the owner or an admin of the session's team writes the ACL row session.grant writes, observe a viewer and control a collaborator, and a row in session_invites of who invited whom and when, which the invitee's list and the session's head read. The pod is pushed acl.changed, so a connection already open meets it at its next command, and invite.changed, which gives the log session_invited (best effort, as share.changed: a dormant session has no tree, and the row is the record). session.uninvite removes both, pushes role: null, which the pod's mirror holds as refused, and session_uninvited. Both are audited.

Who may be invited. A person the session's profile covers: a member of a team granted the profile, whose rules they would act under. Anyone else is forbidden with not on this profile's teams and the profile. A platform admin may be invited by anybody. A service principal never: it has nobody to tell and its sessions are a team's. people.search, prefix on the display name, email or subject, offers only people who share a team with the caller and, given a session they may invite into, those its profile covers, at most 25.

Told over the watch. invites.changed {invites}, the whole list, on the watch socket Decision 942 opened (initialize carries invites and capabilities.invites_changed), each time an invitation to that person changes, and invites.list over /rpc for a plane from before or a watch that is down.

A private session

The key follows the invitation into the invitee's own slot, not a wrapped copy on the plane. The brief allowed a transit rewrap or a wrapped-key row. Neither is open to the plane without the raw key: transit rewraps to a newer version of the same key, never to another, and the plane may read no key. So the owner's daemon, the one holder of the key, hands it over: it asks the plane where the invitee's slot is (session.invite_slot, which refuses whom session.invite would, before anything is put anywhere), signs in at the key manager as the owner, and puts each generation of the key at troupe/people/<invitee>/invited/<session>/k<n>-<random> with create and nothing else; then session.invite names those paths (keys), one per generation, or is refused. The person policy gains exactly that rule (create on people/+/invited/*), and OpenBao prefers the invitee's own rule for their own subtree, since its first wildcard comes later, so they read it and nobody else can. A per-person transit key was tried first: a transit key name may not hold @ or |, which people's names do, and a templated policy cannot hash.

What the plane can and cannot read. It holds the paths, and with the new troupe-plane-invites grant may delete their metadata, which destroys every version, and nothing on the data path: it cannot read the session's key, a copy of it, or a byte of the log, which stays sealed under keys only the owner and the invitees hold. The owner cannot read back what it put in another's slot nor overwrite it (proven against OpenBao), a person not invited cannot read the slot, and an invitee reads only their own. Invitees read the sealed copy through session.keys (an assertion for their own name and the paths) and session.presign/session.objects for get and head only.

The invitee reads it on their own machine, not in the console. The brief had the console render it. A page the plane serves could only decrypt it with code the plane serves, which would make "the plane cannot read it" depend on the plane not changing that code. So the daemon reads it (session.read_sealed), the desktop app shows it as Shared with you, and the console lists it with where to read it.

Followed, not steered. This departs from the brief, which had a control invitee steer it "when the owner offers the session". Decision 921 never offers a private session, and the relay carries what an offered session says past the plane in the clear; offering one to its invitees would end the property this decision is for. So a private session's invitation is observe, and control is refused saying why; lifting 921 for invitees is the maintainer's call, not this one's.

Revoking re-keys forward. session.uninvite destroys the person's copies and marks the row rekey_due; the owner's daemon seals what is pending under the key it holds, makes the next generation at <session>.k<n> (a path of its own, since KV keeps a bounded number of versions and the oldest going would lose the start of the log), seals everything after under it (Sealer.rekey/4), puts it in the slot of each person still invited, and reports it (session.rekeyed, refused where a person still invited has no key in it); then the log says session_uninvited. Done at once when the daemon can; otherwise at the next link that carries the session on, before anything more is sealed. A segment is under one generation, and a reader with several tries each: AES-GCM verifies under one only, so the format is unchanged. What was read stays read: the plane stops serving them and the slot copy goes, but they may have kept what they read and its key, and the docs say so.

The daemon's own log decides whom a new key goes to. It puts a new key only in the slots of people the plane lists and the session's own session_invited events name; a plane that listed somebody this machine never invited gets no key for them, and its refusal of the rest leaves the session rekey_due.

Erasure destroys every copy. The invitees' copies first, then every generation and one past the last reported; the session is erasure_pending until all are gone (Decision 756's rule, extended), and a plane without the invites grant leaves such an erasure pending.

Not in this

  • A copy put in a slot for an invitation the plane then refuses stays in the invitee's slot: the slot check before makes it a race, and nothing but the plane may delete there.
  • A dormant pod session gets no log line for an invitation until it is told again.

Governs: apps/troupe_plane/lib/troupe/plane/invites.ex, apps/troupe_protocol/lib/troupe/kms.ex, apps/troupe_protocol/lib/troupe/sessions/sealer.ex, apps/troupe_gateway/lib/troupe/gateway/invites.ex, apps/troupe_gateway/lib/troupe/gateway/private.ex