March 2024 Protocol Updates

[bnewbold]

The Bluesky team has been making good progress implementing our Composable Moderation system. We will be sharing more technical and protocol details when that is initially launched, but there are a few related protocol and infrastructure details that we wanted to give developers a heads up about.

Labeler HTTP Header: clients are partially responsible for selecting and configuring labeling services, and they indicate their configuration in an HTTP request header, which gets forwarded on from the PDS to the AppView. This header is somewhat similar to HTTP content negotiation for language or encoding. If the header is missing, the AppView will assume a default. Not all forms of moderation are configurable in all clients, and not all are controlled by this header; some take place at the infrastructure level.
UPDATE: details in Label specs: https://atproto.com/specs/label

Generic HTTP Proxying: to date, the PDS has proxied specific atproto HTTP requests to specific backend AppViews, based on hardcoded configuration. We are adding a new HTTP header which allows the client to control which service should be used for a given request. The header will work by specifying a DID and service fragment identifier; the PDS resolves the identity (presumably cached) and forwards to the indicated service endpoint. We will have some basic security and abuse mechanisms in place, and expect to formalize and extend those in the future.
UPDATE: details added to atproto HTTP specs: https://atproto.com/specs/xrpc#service-proxying

New DID document service and keys: moderation services will be a new type of server in the atproto network architecture. Every moderation service will have an associated long-term "service identity" (DID). A distinct key will be indicated in the DID doc for use signing labels, distinct from the atproto repo signing key. A new service endpoint will indicate the network location of the moderation service.
UPDATE: details in Label specs: https://atproto.com/specs/label

Moderation Report Routing: moderation reports can be routed to multiple labeling services, based on the type of report and the user's subscribed labeler services. This behavior will make use of HTTP proxying (see above) and be controlled by the client. This behavior will be visible and configurable when creating a report in the app.
UPDATE: report routing using service proxy mechanism described above, with client making a separate request for each service the report is sent to.

Label Schema: labels are a free-standing protocol-level object, which happen to have a Lexicon representation. The schema is being updated to include an expiration timestamp and a signature field; as well as a schema version field in canonical serialization. Signatures will not normally be passed through to end clients, they are for service-to-service validation. More details coming soon.
UPDATE: details in Label specs: https://atproto.com/specs/label

Service Auth Token Updates: to date, JWTs for service-to-service authentication have used the #atproto repo signing key from service DID documents. The issuer JWT field will now (optionally) allow a DID plus #-separated identifier to indicate the specific service used for signing and verification. The service identifiers correspond to service endpoints in DID documents, and to signing keys. For now the mapping between service endpoint identifiers and service signing keys will be fixed (defined in atproto specs). This will enable using non-repo-signing keys, and make key rotation easier.
UPDATE: HTTP API ("XRPC") auth specs have been updated: https://atproto.com/specs/xrpc#inter-service-authentication-jwt

Ozone API Namespace: several of the backend moderation APIs which have been in the com.atproto.admin.* namespace will be moved to a new tools.ozone.* namespace. This will clarify that they are Ozone-specific APIs, not part of the core protocol. Core schemas like reporting and labels will stay in the com.atproto namespace.
UPDATE: this change has been merged to the lexicons in github, and the golang SDK (indigo). The TypeScript SDK has been updated, but the @atproto/api package has not been released. Docs available at: https://docs.bsky.app/docs/category/http-reference and https://github.com/bluesky-social/ozone-ui/blob/main/docs/api.md

Label SDK: the library used to parse hydrated labels on content and determine label behaviors is being updated to work with multiple subscribed labeler services, and custom label values. Part of this will include refactoring and simplifying label behavior rules.
UPDATE: new SDK is discussed here: https://docs.bsky.app/docs/advanced-guides/moderation

Coming Soon

Not changing in the initial launch, but may change soon after:

• specific label values mostly staying the same, but there will be some new values
• moderation report types and categories
• changes to how takedowns are implemented at different pieces of infrastructure
• a new firehose event, #account, for changes to hosted repository status, including new accounts, takedowns, and deletions

Who Is Impacted?

For the most part, these changes should not break or require immediate changes to:

• feed generators
• client applications
• bots and other automation

In particular, existing Bluesky Safety labels will still be applied by default if clients do not configure otherwise, and reports will be routed to the Bluesky Safety team if routing is not specified.

Client applications will be impacted by TypeScript label SDK changes (if they use that package) when they upgrade, and will generally be encouraged to support the new labeler and reporting features. Detailed specifications and documentation will be forthcoming.

The upcoming #account firehose event will impact any direct consumers of the firehose, as well as PDS and Relay implementations.

Service auth changes, HTTP headers, and takedown API changes will impact PDS implementations.