In ActivityPub, a user-level block is created on the blocker’s server and, in
some implementations, communicated to the blocked actor’s server with a Block
activity and later revoked with an Undo Block activity. Many implementations
do not federate blocks at all, and those that do assume every delivery is
received and processed correctly.
Dropped deliveries, software bugs, server crashes and database rollbacks can leave the two servers with different views of which blocks are in effect. This causes two kinds of failure:
sharedInbox and the
receiving server decides what its local users can see.This proposal describes an optional mechanism for detecting and repairing such discrepancies, modeled on [FEP-8fcf]. It discloses a block only to the server that hosts the blocked actor, and only after that server has authenticated itself with a signed request.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this specification are to be interpreted as described in [RFC-2119].
Implementations and deployments MUST NOT implement the mechanisms described in this proposal unless:
id, inbox and sharedInbox URIs;GET requests
(“authorized fetch”) and to sign its own outgoing requests, using
[HTTP-Signatures] or [RFC-9421].These requirements are the same as those of [FEP-8fcf], plus signed fetch. They
ensure that the set of blocks relevant to a peer can be derived from actor
ids alone, and that the requesting peer can be identified reliably.
Implementing this proposal is optional and does not affect compatibility with implementations that do not support it.
(blocker, blocked) of actor ids, meaning
the actor blocker has blocked the actor blocked.blocker
shares the sending instance’s authority and the blocked actor shares the
receiving instance’s authority.An instance implementing this proposal MUST use the same disclosure set when computing digests and when serving the synchronization endpoint. A block pair that is not part of the disclosure set MUST NOT contribute to any digest and MUST NOT be returned by the synchronization endpoint.
This prevents a peer from testing guesses about undisclosed blocks against the digest.
The block set digest summarizes a relevant block set so that two instances can check cheaply whether they agree.
For each block pair, compute the SHA-256 hash of the UTF-8 encoding of the
blocker id, a single space character (U+0020), and the blocked id. The
digest is the XOR of all of these hashes, encoded as 64 lowercase hexadecimal
characters:
pairHash(blocker, blocked) = SHA256(blocker + " " + blocked)
digest = pairHash(pair1) XOR pairHash(pair2) XOR ... XOR pairHash(pairN)
Actor ids are used exactly as they appear in the actor documents, with no
normalization. The digest of an empty set is 64 zero characters.
Suppose https://a.example has the following disclosure set:
https://a.example/users/alice blocks https://b.example/users/bobhttps://a.example/users/carol blocks https://b.example/users/bobhttps://a.example/users/alice blocks https://c.example/users/daveThe relevant block set for https://b.example contains the first two pairs:
SHA256("https://a.example/users/alice https://b.example/users/bob")
= 5a0f09e214e8951a292c01ce220e3b768e738ab28917c73a3ced82e8fd8c77c2
SHA256("https://a.example/users/carol https://b.example/users/bob")
= 086808bc95e0f2fa3db8e55ae0c5d80e70e87aecc74a7d6beab2ba2319280a17
digest
= 5267015e810867e01494e494c2cbe378fe9bf05e4e5dba51d65f38cbe4a47dd5
Block-Synchronization HTTP headerThe Block-Synchronization header lets the sending instance tell the receiving
instance what its relevant block set currently looks like, and where to fetch
it.
The header value is a list of parameters and values, formatted according to
the signature syntax defined in [HTTP-Signatures], Section 4.1, as in
[FEP-8fcf].
Block-Synchronization: url="https://a.example/federation/block-sync", digest="5267015e810867e01494e494c2cbe378fe9bf05e4e5dba51d65f38cbe4a47dd5"
url: the URL of the synchronization endpoint. It MUST share the sending
instance’s authority.digest: the block set digest of the relevant block set for the receiving
instance.A separate header is used rather than Collection-Synchronization because
[FEP-8fcf] requires that header’s collectionId to be a followers collection.
The synchronization endpoint returns the relevant block set for the instance that makes the request. The same URL serves every peer; the response depends on who the requester has proven to be.
Requests to the synchronization endpoint MUST be signed using [HTTP-Signatures] or [RFC-9421]. The serving instance MUST:
id
shares the authority of the key’s id;id as the requesting authority.Requests SHOULD be signed by the requesting instance’s application actor. The serving instance MUST NOT accept a requesting authority from any other source, such as a query parameter or request header.
If the request is unsigned or the signature cannot be verified, the serving
instance MUST respond with 401 Unauthorized. If the serving instance does not
disclose blocks to the requesting authority, it MUST respond with
403 Forbidden rather than an empty collection, because an empty collection
would instruct the requester to remove all of its recorded blocks.
A successful response is an OrderedCollection whose items are objects of
type Block, each with an actor and an object property containing the
blocker and blocked actor ids. An id for each Block MAY be included but
is not used by this proposal.
The collection MUST contain exactly the relevant block set for the requesting
authority: every block pair in the serving instance’s disclosure set whose
actor shares the serving instance’s authority and whose object shares the
requesting authority, and nothing else.
The collection MUST include a blockSynchronizationDigest property whose value
is the block set digest of the collection’s items, computed from the same state
the items are read from. This lets the receiving instance check that the items
it fetched form a consistent set, including when there was no header to compare
against (see Applying the result). When the collection
is paginated, the property is only required on the top-level collection object.
{
"@context": [
"https://www.w3.org/ns/activitystreams",
{
"blockSynchronizationDigest": "https://w3id.org/fep/070c#blockSynchronizationDigest"
}
],
"type": "OrderedCollection",
"totalItems": 2,
"blockSynchronizationDigest": "5267015e810867e01494e494c2cbe378fe9bf05e4e5dba51d65f38cbe4a47dd5",
"orderedItems": [
{
"type": "Block",
"actor": "https://a.example/users/alice",
"object": "https://b.example/users/bob"
},
{
"type": "Block",
"actor": "https://a.example/users/carol",
"object": "https://b.example/users/bob"
}
]
}
A relevant block set only covers the actors of one peer, so it is usually small. Serving instances SHOULD return it as a single document, and SHOULD only paginate when the set is too large to serve at once.
When a collection is paginated, serving instances SHOULD order items by actor
and then object, and SHOULD link pages with a cursor derived from the last
item of the previous page rather than a numeric offset. With offset-based pages,
removing an item from an earlier page shifts later items so that one of them
can be skipped entirely. With cursor-based pages, a block pair that exists for
the whole duration of a fetch is always returned; only pairs added or removed
during the fetch may or may not appear.
Responses MUST NOT be stored by shared caches. Serving instances SHOULD send
Cache-Control: private, no-store. They SHOULD send an ETag for the
requesting authority’s current relevant block set and honor If-None-Match,
so that periodic reconciliation is cheap when nothing has changed.
Receiving instances learn the endpoint URL from the Block-Synchronization
header and MAY remember it per peer.
An instance MAY additionally advertise the endpoint on its application actor
using the blockSynchronization property, so that peers can reconcile even
when they have not received a delivery carrying the header:
{
"@context": [
"https://www.w3.org/ns/activitystreams",
{
"blockSynchronization": {
"@id": "https://w3id.org/fep/070c#blockSynchronization",
"@type": "@id"
}
}
],
"id": "https://a.example/actor",
"type": "Application",
"blockSynchronization": "https://a.example/federation/block-sync"
}
The advertised URL MUST share the application actor’s authority.
When delivering an activity to an inbox or sharedInbox, an instance MAY
attach a Block-Synchronization header computed for the instance that owns
that inbox, determined by the inbox URI’s authority. Because the digest
describes the whole instance pair, the header MAY be attached to a delivery
signed by any local actor, including the application actor.
The header MUST be covered by the request’s HTTP signature: listed in the
headers parameter under [HTTP-Signatures], or included as a covered component
under [RFC-9421].
An instance MUST NOT attach the header to deliveries to an instance it does not disclose blocks to.
Upon receiving a delivery with a Block-Synchronization header, the receiving
instance MUST check that:
url parameter shares the authority of the signing actor’s id.If either check fails, the receiving instance MUST ignore the header.
The receiving instance SHOULD then compute the digest of the block pairs it has
recorded in which the blocker shares the sender’s authority and the blocked
actor is local. If this digest differs from the digest parameter, it SHOULD
fetch the url, signing the request as described in
Authentication.
Receiving instances SHOULD rate limit fetches per peer and SHOULD collapse repeated mismatches from the same peer into a single pending fetch.
A receiving instance MAY periodically fetch the synchronization endpoint of
peers it federates with, using a URL learned from the header or from the
peer’s application actor, even without a digest mismatch. This covers peers
that rarely deliver to the receiving instance, which is common after a block
has been made. A daily interval per active peer, combined with If-None-Match,
is RECOMMENDED as a starting point.
Adding a block that should not exist is an inconvenience. Removing a block that should exist exposes a user to the actor they blocked. The rules below are therefore asymmetric.
After fetching the collection, the receiving instance MUST discard any item
whose actor does not share the serving instance’s authority or whose object
does not share its own authority, and MUST compute the block set digest of the
items it fetched, across all pages.
For each block pair in the collection but not recorded locally, the receiving
instance SHOULD apply the block as if it had received the corresponding Block
activity. It MAY do so even when the fetch was incomplete or inconsistent.
For each block pair recorded locally but not in the collection, the receiving
instance SHOULD remove the block as if it had received the corresponding
Undo Block activity, but only if all of the following hold:
blockSynchronizationDigest.If the digests differ, the set changed while it was being fetched or the response is inconsistent. The receiving instance MUST NOT remove any block based on that fetch. It MAY retry the fetch once, and otherwise waits for the next mismatch or reconciliation.
Receiving instances SHOULD NOT remove a block pair they recorded within the
last few minutes (10 minutes is RECOMMENDED), even when all of the conditions
above hold. This covers a Block activity that arrived after the serving
instance generated its response.
The digest from a Block-Synchronization header only decides whether to fetch.
Removals are always checked against the digest in the fetched collection, so
header-triggered synchronization and periodic reconciliation follow the same
rules.
Blocks are unilateral, so the receiving instance does not deliver anything in response.
If the fetch fails or returns a non-2xx status, the receiving instance MUST NOT change its recorded blocks for that peer.
Block activitiesThis proposal is independent of how blocks are otherwise communicated. An
instance MAY implement it without ever sending Block activities, relying on
synchronization alone.
Instances that also want blocks to take effect on servers that do not
implement this proposal SHOULD additionally send Block and Undo Block
activities. When both are used, the set of blocks federated as activities
SHOULD match the disclosure set, and synchronization serves as a repair
mechanism for lost or misapplied deliveries.
Blocking an actor typically also removes that actor from the blocker’s followers collection. That side of the relationship is already reconciled by [FEP-8fcf], so the two proposals complement each other.
Blocks are sensitive. This proposal is designed so that implementing it
reveals no more than federating Block activities to the blocked actor’s
server would:
However, disclosing a block to the blocked actor’s server means that server’s operators can see it, and a hostile operator could reveal it to the blocked actor.
Implementations SHOULD therefore:
Receiving implementations SHOULD NOT notify the blocked actor as a result of synchronization. This proposal does not change how implementations present blocks to users.
The XOR of SHA-256 hashes is an order-independent set summary, not a collision-resistant set hash: a party that controls the set’s contents could construct a different set with the same digest. This proposal uses the digest in two ways, neither of which depends on collision resistance:
Receiving instances never infer block state from a digest alone.
The url authority check prevents a sender from making the receiving instance
issue signed requests to third-party servers.
Each digest mismatch can trigger an outbound signed fetch, so rate limiting on both ends is important to prevent amplification.
The digest can be maintained incrementally. When a block pair is added to or
removed from the disclosure set, the instance XORs its pairHash into the
cached digest for the blocked actor’s authority. Storing the digest as 32 bytes
per peer authority, for example in a key-value store, avoids recomputing it on
every delivery.
When an actor is deleted, the instance hosting the blocker SHOULD remove block
pairs involving it from its disclosure set when it processes the Delete.
Receiving instances MAY keep block pairs they cannot currently apply, such as
pairs whose blocker has not been fetched yet, so that their digest stays in
agreement with the serving instance.
Because the serving instance usually already maintains the digest for the
header, it can reuse it both for the collection’s
blockSynchronizationDigest and as the ETag of the response.
Receiving instances that want an immediate second attempt after a digest mismatch during a paginated fetch should wait briefly before retrying, so that a burst of changes on the serving instance has time to settle.
CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
To the extent possible under law, the authors of this Fediverse Enhancement Proposal have waived all copyright and related or neighboring rights to this work.