Arbiter: Group management for Permissioned Spaces

erlend.sh · April 10, 2026, 12:19pm

erlend.sh · April 18, 2026, 8:34pm

Second installment from @zicklag.dev

erlend.sh · April 25, 2026, 6:13pm

So far the short addendum to the arbiter doc should be at least:

Having a special $publish space that allows writing to public records under the arbiter’s DID, if the arbiter has a public repo setup.

Making a note about syncing, that it could go either way, and that we might need to experiment with different solutions. The core implementation is agnostic to sync specifics, and if you don’t use remote space delegation, then you don’t need syncing at all.

Mentioning “adopting” a DID as an option.

Mention that I think when it comes to publishing records to permissioned spaces or a public repo that is an extra feature that isn’t required for all arbiter implementations.

Edit: Also we could have a $labeler role that lets you create / edit / delete labels if you have the ConfigureSpace permission in that space.

A preliminary version of this is being sketched out in @flo-bit.dev’s contrail.

github.com/flo-bit/contrail

docs/06-communities.md

main

# Communities

Group-controlled atproto DIDs. A community is a DID whose signing/rotation keys are held by the appview on behalf of multiple members, with tiered access levels. Built on top of [spaces](./05-spaces.md).

## When to use this

When you want atproto records published under a *shared* identity — a team, a project, a channel — not a single user. Think: a group's published calendar events, a community's published posts.

## Two modes

- **Minted** — contrail creates a fresh `did:plc` for the community, holds the signing key plus one rotation key (a second rotation key is returned to the creator once for recovery), and publishes from it.
- **Adopted** — contrail takes over an existing account by holding an **app password** issued from its PDS. The owner's identity, signing key, and rotation keys are unchanged; contrail just gets PDS write access via the app password.

Either way, the result is the same: a DID that multiple members can act through, gated by access levels.

## Access levels

Each member has a level (ranked). Levels map to write permissions. Owners can grant/revoke levels. Two reserved levels exist: `owner` and `member`. Your deployment defines the rest:

```ts

This file has been truncated. show original

github.com/flo-bit/contrail

docs/05-spaces.md

main

# Spaces

Auth-gated store for records that can't live on public PDSes — private events, invite-only groups, members-only chat. Opt-in; zero cost if you don't enable it.

## Mental model

> A **space** is a bag of records with one lock. The **member list** says who has the key.

- One owner (DID), one type (NSID), one key. Identified by `ats://<owner>/<type>/<key>` — distinct scheme from atproto record URIs (`at://`) so the two can't be confused at any layer.
- Every member (including owner) has read + write inside the space. Delete is scoped to your own records — no one can remove records they didn't author, owner included. To wipe everything, delete the space.
- Optional **app policy** gates which OAuth clients can act in the space.

Every permission boundary is its own space. No nested ACLs. Richer roles = more spaces or app-layer checks.

## Enable

```ts
import type { ContrailConfig } from "@atmo-dev/contrail";

const config: ContrailConfig = {

This file has been truncated. show original

erlend.sh · May 14, 2026, 8:14pm

Latest from zick:

Give the simulator a try!

The demo runs the ACTUAL arbiter core state machine that we are developing for the server, compiled to WASM, and with network messages simulated by the web app.

This means it does all the real access & permissions checks just like the server will.

essentialrandom.bsky.social · May 18, 2026, 2:24am

This is very relevant to the interests of my broader community, and I’d love to try and lead a public discussion/“understanding building” session on stream, probably the week after this coming one. The simulator looks very cool and it’ll definitely be helpful.

I have read the proposal and understand it, but if anyone is willing to be there* to make sure it’s not all in my hand or guide me through it beforehand, I’d love to coordinate.

*time is flexible, but early afternoon Pacific preferred

zicklag.dev · May 18, 2026, 2:29am

Ooh, I’d love to be there and participate however you’d like!

I’m pretty open time-wise.

zicklag.dev · May 18, 2026, 4:56pm

After talking to the Habitat and Acorn folks last week, and thinking about the things we need right after the arbiter, I think there might still be another iteration on the idea of the arbiter that we need to make.

I’m doing some mulling over it, but the short of it is that some usecases and apps are going to need custom “policies” for permissions management. This can be really useful for incorporating things like democratic governance.

Initially the idea was that we should keep the group membership simple, and let apps or “stewards” handle the more complicated policies. But with Habitat needing more complicated policies at the group layer, it looks like the arbiter might not work for them.

Group Interoperability Beyond the Arbiter

Even still we want to have some way for the arbiter and Habitat to work together, ideally. This means we’d want some kind of standard, intermediate idea of group membership.

I think the intermediate representation should support a tree of roles, probably including delegation to remote roles like the arbiter does today.

Significantly this provides the “who is who” of the community, separate from the “what you can do”.

It would be ideal if we could provide a standardized API around this “who is who” that can be the same, regardless of differences between Habitat and the arbiter’s way of figuring out “what you can do”.

That could potentially include XRPC apis for modifying the role membership, creating new roles, deleting them, etc. But the determinitation of whether you have access to take those actions could be different for Habitat and the arbiter.

Extending the Arbiter With Policies

I think that the arbiter’s current design is pretty flexible and would probably handle most use-cases. But while thinking about the kinds of detailed policies that might be needed for community “steward” repositories, I started looking into Open Policy Agent.

Then it occurred to me that if we separate the “who is who” from the “what can you do” with stewards, maybe we can do the same thing in the arbiter, and allow you to provide a custom policy for the arbiter, too, instead of hard-coding the access-level-based mechanism that we have right now.

Probably the biggest advantage would be possibly allowing for things like democratic election / demotion of admins.

For that to work the arbiter and the steward might have to be combined. I.e. Providing the arbiter it’s own repo to store community records in that can be used to inform policy of group consent, etc.

There’s a lot of thinking to be done here and I’m going to be trying this week to figure out a sensible path.

cc @offline.arushibandi.com.

The above is sort of a summary / expanshion of the raw musings below:

Today I’m going to start thinking harder about a way to make Habitat and the Arbiter somewhat more interoperable even if they are different from each-other.

I’m thinking that the common abstraction between them will be hierarchical roles and the members in them.

Nothing I’ve seen other than the arbiter allow cycles in roles. I think in most cases cycles are probably just a bad idea. The arbiter was simple enough for us to have a sensible way of making cycles resolve, but that likely can’t work sensibly without the simplistic access level strategy we used.

So I think that means having a common representation of a role membership tree would be good.

And I’m also considering whether I can just use OPA to protect updates to the role tree on the arbiter.

That would allow different arbiters to have different policies and allow for things like democratic election / demotion of admins and things like that, which would be pretty cool.

I think the hierarchical roles is the important interoperability piece because it represents a significant portion of community identity.

Who is who is crucial to migrating the community to a new arbiter or in drastic scenarios when the community needs to fork and create a new DID.

Having a standardized way of modifying the members in those roles, and being able to create new spaces is important, too.

But maybe if we restrict things a bit more than the arbiter does right now, to require all roles to be trees, but to allow multiple individual members and roles to spaces, then we might be in a better situation inter-op-wise.

That way multiple different implementation can have different ways for controlling who is allowed to put who in different roles, who can delete roles, create roles, create spaces, etc.

But maybe we can have a standardized API for doing it?

And then custom extension APIs per implementation strategy for doing things like setting the actual policies around who can do what to the access rules.

In the arbiter right now we combined the handling of “who is who” and “what can you do”. But “what can you do” on the arbiter can be separated from “who is who”, just like we expected you to separate that for the apps.

zicklag.dev · May 20, 2026, 12:43am

OK, I have some draft lexicons for the idea above now:

Docs site generated from the lexicons:

And the JSONs are on lexicon.garden:

The idea is that we define the basic structure of Arbiters with spaces with members, but we allow the arbiter, the spaces, and the members each to hold an arbitrary lexicon object by making it an open union.

The expectation is that different arbiter servers can implement custom lexicons to fill in those open unions, and that they will also implement custom mechanisms for authentication ( i.e. are you allowed to add that member or create that space? ).

Regardless of the authentication mechanism it uses, any client that supports these lexicons will be able to read the list of spaces, and see who is a member.

The abilty to add spaces as members of other spaces is considered important enough to be built-in. This allows us to represent subgroups and role trees in an interoperable way.

I think this achieves the separation of “who is who” from “what can you do” and now the question will be whether or not this API is suitable for both Habitat and our own arbiter.

I think if this works out, then it’d be a perfect candidate for lexicon.community. But we should probably make sure that can actually get two separate servers that can both use this API first.

zicklag.dev · May 22, 2026, 3:05pm

Another update here:

I should have an updated simulator today using the new policy system. It works essentially the same as before, but now it’s generic over the policy so it can hypothetically be customized for things like voting / election workflows.

I’ll be working on an actually useful implementation very soon, which will essentially be an alternative to opensocial.community, but with more advanced policy support and the intention to act as a space host for permissioned data.

essentialrandom.bsky.social · May 23, 2026, 7:53am

Just confirming again my intention to do this since it took me a while to get back to you. I’ll be reaching out in private to schedule a chat, and we can find a date that works!

Definitely have a few docs to read through.