Skip to content

docs(rooms): an operator guide for creating and running a data room - #1273

Merged
stormer78 merged 1 commit into
mainfrom
docs/data-rooms-operator-guide
Sep 7, 2026
Merged

docs(rooms): an operator guide for creating and running a data room#1273
stormer78 merged 1 commit into
mainfrom
docs/data-rooms-operator-guide

Conversation

@stormer78

Copy link
Copy Markdown
Contributor

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.1 is authorized by nothing On both hosts: the document's proof is not checked on that verb, the signer is not compared to ownerDid, and no policy consults anything. Anyone who can reach the endpoint can register a room row. Every other verb verifies properly
Role::Application carries neither roomPresent nor roomOpen The role agent integrations run as cannot use the oracle built for agents; today that needs initiator or admin, which is broader than the design intends
No installer consumes a room or room-host bundle The templates mint the DID shape, but extracting the room's signing key to issue credentials with means opening the sealed payload by hand
The room epoch is the MLS epoch plus one The off-by-one that seals records under an epoch the host rejects — and the failure reads as a key problem, not an arithmetic one

Stale status corrected

docs/05-design-notes/data-rooms.md still 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.

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant