Atproto spaces alpha updates

Working Groups WG Private Data
7

We just cut another spaces alpha release today!

This is the biggest yet, there are multiple breaking changes across core protocol pieces. This is likely the last/only release of this size. Though we are planning to do a smaller (tho still substantial & backwards-incompatible) release next Thursday. The hope is that that will be the last breaking alpha release. Then we can use November to do final shakeout, before moving to beta at the end of the month.

I expect this rollout to be somewhat disruptive. We have updated the hosted spaces alpha PDS, the Docker image at ghcr.io/bluesky-social/atproto:pds-spaces-alpha and the relevant npm packages. For folks running their own PDS, this release includes database migrations on both the account manager DB & the actor store DBs as well as adding a new per-account key which will require a DID doc update for each account (see below).

Like last time, we’ve put together a prompt that you can give your coding agent to handle the migration.

To summarize the changes:

  • Shared secret commits. This is the biggest change. Space repo commit HMACs are now done using a negotiated shared secret between a syncer and a repo host. This requires introducing a new #atproto_kem key for each user and commit MACs are sent in HTTP headers. We also tweaked some field names in the commit such as hash → data. Rationale is in this thread. (Implementation / Proposal)
  • STAR files. getRepo now returns a STAR archive instead of a CAR file. Thanks @bad-example.com! (Implementation / Proposal)
  • Public spaces. Spaces can issue credentials without a delegation token. As part of this, we moved the delegation token & HTTP signature key material to the request body of getSpaceCredential (instead of headers). Also tweaked the authorization scheme name for consistency. (Implementation / Proposal)
  • Simpler DID doc keys. To avoid some complexity, we ditched the new space host signing key & service endpoint in DID docs. Space authorities resolve like any other account: #atproto_pds is the space host and #atproto signs credentials. (Implementation / Proposal)
  • Reliable space deletion. Space authorities retry notifySpaceDeleted until it’s delivered or the syncer’s registration expires. This mirrors the robust delivery of write notifications from repo host to space host. (Implementation / Proposal)

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

We also updated the version of Node in the published Docker image in response to the eMudhra CA compromise.

A note on KEM keys: every account with space repos now needs an #atproto_kem key in its DID doc. New accounts get one automatically. For existing accounts, the PDS runs a one-time background backfill on startup that generates the key & publishes an update PLC. This should Just Work :trade_mark:! However, it touches every account on the PDS, so self-hosters should expect a PLC update and an #identity event per account. If your account uses did:web, or your PDS can’t update your PLC doc, you’ll need to add the key yourself (getRecommendedDidCredentials returns it). Until an account’s key is published, its space repos can’t be synced. Account migration tools also need to carry atproto_kem through from getRecommendedDidCredentials, since submitPlcOperation now checks it.

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

10 Likes