docs(rooms): an operator guide for creating and running a data room - #1273
Merged
Conversation
Data rooms shipped across nine PRs (#1237-#1251) with no operator documentation: the doc set was a design note, two security reviews, and a concept page, none of which tells anyone how to create a room or run a host. This adds the missing guide, written against the implementation rather than the design note. `docs/02-vta/data-rooms.md` covers all four topologies end to end - the pieces a room is made of, choosing a topology and a visibility tier, creating the room (identity, registration, the owner's own credentials, the MLS group), adding a member, equipping an agent through the oracle, using records, renewal, transfer and claim, running each kind of host, a refusal-to-cause table, and a reference of task URIs, gates and constants. `docs/02-vta/data-rooms-guide.html` is the same path as a readable page, in the concept document's design language. Verifying each claim against the code turned up four things worth stating rather than smoothing over, and the guide names all of them: `rooms/create/0.1` is authorized by nothing on either host, so anyone who can reach the endpoint can register a room row; `Role::Application` carries neither `roomPresent` nor `roomOpen`, so the role agents run as cannot use the oracle built for agents; no installer consumes a `room` or `room-host` bundle, so the room's signing key has to be extracted by hand; and the room epoch is the MLS epoch plus one, which is the off-by-one that reads as a key failure. Both HTML pages and the design note also carried a stale status - the note still opened with "Nothing is implemented" while its own section 10 described succession as implemented. All three now say what is built and what is not. Signed-off-by: Glenn Gore <glenn.g@affinidi.com>
This was referenced Sep 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Data rooms shipped across nine PRs (#1237–#1251) with no operator documentation. The doc set was a design note, two security reviews and a concept page — none of which tells anyone how to create a room or run a host. This adds the missing guide, written against the implementation rather than the design note.
What's here
docs/02-vta/data-rooms.md— the guide, covering all four topologies end to end: the pieces a room is made of, choosing a topology and a visibility tier, creating the room (identity → registration → the owner's own credentials → the MLS group), adding a member, equipping an agent through the oracle, using records, renewal, transfer and claim, running each kind of host, a refusal-to-cause table, and a reference of task URIs, gates and constants.docs/02-vta/data-rooms-guide.html— the same path as a readable page, in the concept document's design language, with diagrams of the four topologies, who calls what, and the lifecycle clock.docs/README.md— a Part II entry, an "If you're trying to…" row, and the design-note entry now points at the guide.Four things verification turned up
Checking every claim against the code found four worth stating rather than smoothing over. The guide names all of them:
rooms/create/0.1is authorized by nothingownerDid, and no policy consults anything. Anyone who can reach the endpoint can register a room row. Every other verb verifies properlyRole::Applicationcarries neitherroomPresentnorroomOpeninitiatororadmin, which is broader than the design intendsroomorroom-hostbundleStale status corrected
docs/05-design-notes/data-rooms.mdstill opened with "Nothing is implemented. The upstream spec work has not started" while its own §10 described succession as implemented; the concept HTML said the same and named a branch that no longer exists. Both now say what is built and what is not.Docs only — no code, no version edits.