Atproto spaces alpha updates

Working Groups WG Private Data
12

Just cut the release for today, and updated the alpha spaces PDS.

As @bnewbold.net mentioned, this is a bigger set of changes than we’d hoped for this late in the alpha. But I also think they’re pretty big improvements. Thanks for bearing with us! We know these updates cause a lot of churn. But everything is about 1000x easier to change now than it will be in 3 weeks. We’re trying to take care to respect the folks building on/with the alpha while still specifying the best protocol we can.

I actually really do expect this to be the last breaking change like this. The only remaining thing is possibly updating the URI format. I’d say I’m about 75% confident we’ll end up going with at:space/ but we want to build a bit more confidence during our trip to the IETF next week that that’s a viable path for a unified URI format.

Besides that, the next couple weeks will be mostly focused on final fine-tuning/polishing and operationalizing things. I’m sincerely hoping that besides the URI format, we have no more backwards-incompatible changes to the spec (though I can’t guarantee that).

Per usual, we’ve published alpha versions of the relevant NPM packages, published a new Docker image at ghcr.io/bluesky-social/atproto:pds-spaces-alpha and updated the hosted spaces alpha PDS. This release does include database migrations across both the account manager DB & actor store DBs.

We’ve put together a prompt that you can give your coding agent to handle the migration.

To summarize the changes:

  • Lexicon refactor: We went back over every spaces Lexicon to make names, fields & errors consistent as well as just generally tightening up the semantics. (Implementation / Proposal)
  • SDK Refactor: We did a similar pass over the SDKs as well. This is mostly just implementation work, but it turned up a small thing or two in the spec. (Implementation / Proposal)
  • lex-space package: @matthieu.bsky.team put together an excellent new higher-level SDK for working with spaces built on @atproto/lex. It handles the whole credential dance and gives you typed reads & writes (Implementation)
  • Space notifications: We refactored how space notifications to syncers work. Syncers now register when they get a space credential, and notifications take the form of webhooks. We increased the reliability of notifications for syncers whose registration has expired. And to reflect the change in sematnics of the route (and to avoid the strange use of get for a side-effect-full route), we renamed the core method from getSpaceCredential → authorizeSpaceSync. (Implementation / Proposal)
  • MACs in HTTP Signatures: We had HTTP Signatures elsewhere in the spec, but then our own invented HTTP headers for transmitting repo & record MACs. We opted to standardize on HTTP Signatures here as well. (Implementation / Proposal)
  • HPKE Secret export: The KEM shared secret is now derived from HPKE’s standard Secret Export mode. This prevents us from speccing our scheme, and many languages support this in standard HPKE packages. If your language doesn’t support it, the proposal has an appendix with the equivalent ECDH + HKDF steps. (Implementation / Proposal)
  • Repo lifecycle: A couple of things to tighten up repo lifecycle including clarification of garbage collection semantnics for empty repos and delivering removal from the writer set over notifications & listWriters. (Implementation / Proposal)
  • Merge main: We merged the last several months of activity from main into the permissioned-data feature branch. There are some muddled DB migrations as a result. It should all work fine as you upgrade spaces alpha PDSes, and we’ll refactor & squash all of these down before cutting the beta release and merging this into main. (Implementation)
  • Moderation guidance: We clarified that labels on space data are published as com.atproto.label.records in the same space as the content they label. This section also lays out baseline takedown capabilties for each kind of service. (Implementation / Proposal)
  • Access control in applications guidance: This addition to the proposal does not change any protocol mechanisms, but instead gives guidance to applications and applciation developers for determining which of their users can see what space data (Proposal)

All the spec changes for this release are combined in proposals#143.

As always, please let me know if you have feedback or if you run into bugs or sharp edges!

5 Likes