Implement FEP-8fcf followers collection synchronization (#2297)

Author: pfefferle

.github/changelog/2297-from-description

@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Added support for FEP-8fcf follower synchronization, improving data consistency across servers with new sync headers, digest checks, and reconciliation tasks.

FEDERATION.md

@@ -24,6 +24,7 @@ The WordPress plugin largely follows ActivityPub's server-to-server specificatio
 - [FEP-844e: Capability discovery](https://codeberg.org/fediverse/fep/src/branch/main/fep/844e/fep-844e.md)
 - [FEP-044f: Consent-respecting quote posts](https://codeberg.org/fediverse/fep/src/branch/main/fep/044f/fep-044f.md)
 - [FEP-3b86: Activity Intents](https://codeberg.org/fediverse/fep/src/branch/main/fep/3b86/fep-3b86.md)
+- [FEP-8fcf: Followers collection synchronization across servers](https://codeberg.org/fediverse/fep/src/branch/main/fep/8fcf/fep-8fcf.md)
 
 Partially supported FEPs
 

includes/class-handler.php

@@ -9,6 +9,7 @@
 
 use Activitypub\Handler\Accept;
 use Activitypub\Handler\Announce;
+use Activitypub\Handler\Collection_Sync;
 use Activitypub\Handler\Create;
 use Activitypub\Handler\Delete;
 use Activitypub\Handler\Follow;
@@ -37,6 +38,7 @@ public static function init() {
 	public static function register_handlers() {
 		Accept::init();
 		Announce::init();
+		Collection_Sync::init();
 		Create::init();
 		Delete::init();
 		Follow::init();

includes/class-http.php

@@ -53,6 +53,7 @@ public static function post( $url, $body, $user_id ) {
 			'body'                => $body,
 			'key_id'              => \json_decode( $body )->actor . '#main-key',
 			'private_key'         => Actors::get_private_key( $user_id ),
+			'user_id'             => $user_id,
 		);
 
 		$response = \wp_safe_remote_post( $url, $args );

includes/class-scheduler.php

@@ -14,6 +14,7 @@
 use Activitypub\Collection\Outbox;
 use Activitypub\Collection\Remote_Actors;
 use Activitypub\Scheduler\Actor;
+use Activitypub\Scheduler\Collection_Sync;
 use Activitypub\Scheduler\Comment;
 use Activitypub\Scheduler\Post;
 
@@ -60,6 +61,7 @@ public static function init() {
 	public static function register_schedulers() {
 		Post::init();
 		Actor::init();
+		Collection_Sync::init();
 		Comment::init();
 
 		/**

includes/class-signature.php

@@ -465,4 +465,97 @@ public static function generate_digest( $body ) {
 		$digest = \base64_encode( \hash( 'sha256', $body, true ) ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_encode
 		return "SHA-256=$digest";
 	}
+
+	/**
+	 * Compute the collection digest for a specific instance.
+	 *
+	 * Implements FEP-8fcf: Followers collection synchronization.
+	 * The digest is created by XORing together the individual SHA256 digests
+	 * of each follower's ID.
+	 *
+	 * @see https://codeberg.org/fediverse/fep/src/branch/main/fep/8fcf/fep-8fcf.md
+	 *
+	 * @param array $collection The user ID whose followers to compute.
+	 *
+	 * @return string|false The hex-encoded digest, or false if no followers.
+	 */
+	public static function get_collection_digest( $collection ) {
+		if ( empty( $collection ) || ! is_array( $collection ) ) {
+			return false;
+		}
+
+		// Initialize with zeros (64 hex chars = 32 bytes = 256 bits).
+		$digest = str_repeat( '0', 64 );
+
+		foreach ( $collection as $item ) {
+			// Compute SHA256 hash of the follower ID.
+			$hash = hash( 'sha256', $item );
+
+			// XOR the hash with the running digest.
+			$digest = self::xor_hex_strings( $digest, $hash );
+		}
+
+		return $digest;
+	}
+
+	/**
+	 * XOR two hexadecimal strings.
+	 *
+	 * Used for FEP-8fcf digest computation.
+	 *
+	 * @param string $hex1 First hex string.
+	 * @param string $hex2 Second hex string.
+	 *
+	 * @return string The XORed result as a hex string.
+	 */
+	public static function xor_hex_strings( $hex1, $hex2 ) {
+		$result = '';
+
+		// Ensure both strings are the same length (should be 64 chars for SHA256).
+		$length = \max( \strlen( $hex1 ), \strlen( $hex2 ) );
+		$hex1   = \str_pad( $hex1, $length, '0', STR_PAD_LEFT );
+		$hex2   = \str_pad( $hex2, $length, '0', STR_PAD_LEFT );
+
+		// XOR each pair of hex digits.
+		for ( $i = 0; $i < $length; $i += 2 ) {
+			$byte1   = \hexdec( \substr( $hex1, $i, 2 ) );
+			$byte2   = \hexdec( \substr( $hex2, $i, 2 ) );
+			$result .= \str_pad( \dechex( $byte1 ^ $byte2 ), 2, '0', STR_PAD_LEFT );
+		}
+
+		return $result;
+	}
+
+	/**
+	 * Parse a Collection-Synchronization header (FEP-8fcf).
+	 *
+	 * Parses the signature-style format used by the Collection-Synchronization header.
+	 *
+	 * @see https://codeberg.org/fediverse/fep/src/branch/main/fep/8fcf/fep-8fcf.md
+	 *
+	 * @param string $header The header value.
+	 *
+	 * @return array|false Array with parsed parameters (collectionId, url, digest), or false on failure.
+	 */
+	public static function parse_collection_sync_header( $header ) {
+		if ( empty( $header ) ) {
+			return false;
+		}
+
+		// Parse the signature-style format: key="value", key="value".
+		$params = array();
+
+		if ( \preg_match_all( '/(\w+)="([^"]*)"/', $header, $matches, PREG_SET_ORDER ) ) {
+			foreach ( $matches as $match ) {
+				$params[ $match[1] ] = $match[2];
+			}
+		}
+
+		// Validate required fields for FEP-8fcf.
+		if ( empty( $params['collectionId'] ) || empty( $params['url'] ) || empty( $params['digest'] ) ) {
+			return false;
+		}
+
+		return $params;
+	}
 }

includes/collection/class-followers.php

@@ -7,9 +7,11 @@
 
 namespace Activitypub\Collection;
 
+use Activitypub\Signature;
 use Activitypub\Tombstone;
 
 use function Activitypub\get_remote_metadata_by_actor;
+use function Activitypub\get_rest_url_by_path;
 
 /**
  * ActivityPub Followers Collection.
@@ -567,4 +569,108 @@ public static function remove_blocked_actors( $value, $type, $user_id ) {
 
 		self::remove( $actor_id, $user_id );
 	}
+
+	/**
+	 * Compute the partial follower collection digest for a specific instance.
+	 *
+	 * Implements FEP-8fcf: Followers collection synchronization.
+	 * This is a convenience wrapper that filters followers by authority and then
+	 * computes the digest using the standard FEP-8fcf algorithm.
+	 *
+	 * The digest is created by XORing together the individual SHA256 digests
+	 * of each follower's ID.
+	 *
+	 * @see https://codeberg.org/fediverse/fep/src/branch/main/fep/8fcf/fep-8fcf.md
+	 * @see Signature::get_collection_digest() for the core digest algorithm
+	 *
+	 * @param int    $user_id   The user ID whose followers to compute.
+	 * @param string $authority The URI authority (scheme + host) to filter by.
+	 *
+	 * @return string|false The hex-encoded digest, or false if no followers.
+	 */
+	public static function compute_partial_digest( $user_id, $authority ) {
+		// Get followers filtered by authority.
+		$followers    = self::get_by_authority( $user_id, $authority );
+		$follower_ids = \wp_list_pluck( $followers, 'guid' );
+
+		// Delegate to the core digest computation algorithm.
+		return Signature::get_collection_digest( $follower_ids );
+	}
+
+	/**
+	 * Get partial followers collection for a specific instance.
+	 *
+	 * Returns only followers whose ID shares the specified URI authority.
+	 * Used for FEP-8fcf synchronization.
+	 *
+	 * @param int    $user_id   The user ID whose followers to get.
+	 * @param string $authority The URI authority (scheme + host) to filter by.
+	 *
+	 * @return \WP_Post[] Array of WP_Post objects.
+	 */
+	public static function get_by_authority( $user_id, $authority ) {
+		$posts = new \WP_Query(
+			array(
+				'post_type'      => Remote_Actors::POST_TYPE,
+				'posts_per_page' => -1,
+				'orderby'        => 'ID',
+				'order'          => 'DESC',
+				// phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_query
+				'meta_query'     => array(
+					'relation' => 'AND',
+					array(
+						'key'   => self::FOLLOWER_META_KEY,
+						'value' => $user_id,
+					),
+					array(
+						'key'     => '_activitypub_inbox',
+						'compare' => 'LIKE',
+						'value'   => $authority,
+					),
+				),
+			)
+		);
+
+		return $posts->posts ?? array();
+	}
+
+	/**
+	 * Generate the Collection-Synchronization header value for FEP-8fcf.
+	 *
+	 * @param int    $user_id   The user ID whose followers collection to sync.
+	 * @param string $authority The authority of the receiving instance.
+	 *
+	 * @return string|false The header value, or false if cannot generate.
+	 */
+	public static function generate_sync_header( $user_id, $authority ) {
+		$followers = self::get_by_authority( $user_id, $authority );
+		$followers = \wp_list_pluck( $followers, 'guid' );
+
+		// Compute the digest for this specific authority.
+		$digest = Signature::get_collection_digest( $followers );
+
+		if ( ! $digest ) {
+			return false;
+		}
+
+		// Build the collection ID (followers collection URL).
+		$collection_id = get_rest_url_by_path( sprintf( 'actors/%d/followers', $user_id ) );
+
+		// Build the partial followers URL.
+		$url = get_rest_url_by_path(
+			sprintf(
+				'actors/%d/followers/sync?authority=%s',
+				$user_id,
+				rawurlencode( $authority )
+			)
+		);
+
+		// Format as per FEP-8fcf (similar to HTTP Signatures format).
+		return sprintf(
+			'collectionId="%s", url="%s", digest="%s"',
+			$collection_id,
+			$url,
+			$digest
+		);
+	}
 }

includes/collection/class-following.php

@@ -347,6 +347,44 @@ public static function query_all( $user_id, $number = -1, $page = null, $args =
 		return self::query( $user_id, $number, $page, $args );
 	}
 
+	/**
+	 * Get partial followers collection for a specific instance.
+	 *
+	 * Returns only followers whose ID shares the specified URI authority.
+	 * Used for FEP-8fcf synchronization.
+	 *
+	 * @param int    $user_id   The user ID whose followers to get.
+	 * @param string $authority The URI authority (scheme + host) to filter by.
+	 * @param string $state     The following state to filter by (accepted or pending). Default is accepted.
+	 *
+	 * @return array Array of follower URLs.
+	 */
+	public static function get_by_authority( $user_id, $authority, $state = self::FOLLOWING_META_KEY ) {
+		$posts = new \WP_Query(
+			array(
+				'post_type'      => Remote_Actors::POST_TYPE,
+				'posts_per_page' => -1,
+				'orderby'        => 'ID',
+				'order'          => 'DESC',
+				// phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_query
+				'meta_query'     => array(
+					'relation' => 'AND',
+					array(
+						'key'   => $state,
+						'value' => $user_id,
+					),
+					array(
+						'key'     => '_activitypub_inbox',
+						'compare' => 'LIKE',
+						'value'   => $authority,
+					),
+				),
+			)
+		);
+
+		return $posts->posts ?? array();
+	}
+
 	/**
 	 * Get all followings of a given user.
 	 *

includes/collection/class-remote-actors.php

@@ -514,7 +514,7 @@ public static function normalize_identifier( $actor ) {
 
 		// If it's an email-like webfinger address, resolve it.
 		if ( \filter_var( $actor, FILTER_VALIDATE_EMAIL ) ) {
-			$resolved = \Activitypub\Webfinger::resolve( $actor );
+			$resolved = Webfinger::resolve( $actor );
 			return \is_wp_error( $resolved ) ? null : object_to_uri( $resolved );
 		}
 

includes/functions.php

@@ -1811,3 +1811,20 @@ function extract_name_from_uri( $uri ) {
 
 	return $name;
 }
+
+/**
+ * Get the authority (scheme + host) from a URL.
+ *
+ * @param string $url The URL to parse.
+ *
+ * @return string|false The authority, or false on failure.
+ */
+function get_url_authority( $url ) {
+	$parsed = wp_parse_url( $url );
+
+	if ( ! $parsed || empty( $parsed['scheme'] ) || empty( $parsed['host'] ) ) {
+		return false;
+	}
+
+	return $parsed['scheme'] . '://' . $parsed['host'];
+}