Add C2S media upload (uploadMedia endpoint)

.github/changelog/c2s-media-upload

@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Allow third-party apps to upload images, audio, and video to your site via the standard ActivityPub media upload endpoint.

.gitignore

@@ -9,6 +9,7 @@ _site
 .claude/**/*.local*
 .claude/summaries/
 .agents/**/*.local*
+docs/superpowers/
 .cursor
 .DS_Store
 .php_cs.cache

FEDERATION.md

@@ -236,6 +236,12 @@ When the ActivityPub API option is enabled, the plugin exposes OAuth 2.0 endpoin
 
 The loopback allowance from RFC 8252 applies *only* to redirect URI matching. Reserved-but-not-loopback addresses (`0.0.0.0`, link-local `169.254.0.0/16`, RFC1918 private ranges, etc.) are not treated as loopback. CIMD metadata URLs must use `https://`, and the metadata host is resolved and validated against private/reserved ranges before any fetch. Loopback CIMD origins are not supported, even on dev installs.
 
+### Media Upload
+
+Implements the W3C SocialCG `uploadMedia` endpoint at `POST /actors/{user_id}/uploadMedia`. Accepts `multipart/form-data` with a required `file` part and an optional `object` JSON-LD shell, plus a Pleroma-compatible `description` form field as a synonym for `object.name` (alt text). Returns `201 Created` with a `Location` header pointing at the new attachment's AP id and the bare `Image`/`Audio`/`Video` object as the body. Requires the `upload` OAuth scope. The endpoint is advertised on `User` and `Blog` actors via `endpoints.uploadMedia` and is gated behind the "ActivityPub API" site setting.
+
+References: [W3C SocialCG wiki — MediaUpload](https://www.w3.org/wiki/SocialCG/ActivityPub/MediaUpload), [Pleroma `uploadMedia` extension](https://docs-develop.pleroma.social/backend/development/ap_extensions/#uploadmedia).
+
 ## Additional documentation
 
 - Plugin Documentation: [docs/readme.md](docs/readme.md)

activitypub.php

@@ -68,6 +68,7 @@ function rest_init() {
 		( new Rest\OAuth\Authorization_Controller() )->register_routes();
 		( new Rest\OAuth\Clients_Controller() )->register_routes();
 		( new Rest\OAuth\Token_Controller() )->register_routes();
+		( new Rest\Media_Controller() )->register_routes();
 	}
 	( new Rest\Outbox_Controller() )->register_routes();
 	( new Rest\Post_Controller() )->register_routes();

includes/class-attachments.php

@@ -380,12 +380,16 @@ private static function is_allowed_local_path( $file_path ) {
 	 * Uses WordPress image editor to resize large images and convert them
 	 * to WebP format for better compression while maintaining quality.
 	 *
+	 * @since 1.0.0
+	 *
 	 * @param string $file_path     Path to the image file.
 	 * @param int    $max_dimension Maximum width/height in pixels.
 	 *
-	 * @return string The optimized file path.
+	 * @return string The optimized file path. If the source was already an
+	 *                optimal image (or not an image at all), the original
+	 *                path is returned unchanged.
 	 */
-	private static function optimize_image( $file_path, $max_dimension ) {
+	public static function optimize_image( $file_path, $max_dimension ) {
 		// Check if it's an image.
 		$mime_type = \wp_check_filetype( $file_path )['type'] ?? '';
 		if ( ! $mime_type || ! \str_starts_with( $mime_type, 'image/' ) ) {

includes/functions.php

@@ -30,6 +30,33 @@ function get_object_id( $wp_object ) {
 	return null;
 }
 
+/**
+ * Return the canonical ActivityPub URL for a WordPress attachment.
+ *
+ * The URL points at the plugin's media REST endpoint, which serves the
+ * AP-JSON representation of the attachment. Used as the `id` of an
+ * uploaded media object and as the value of the `Location` header on
+ * a successful `uploadMedia` response.
+ *
+ * @since unreleased
+ *
+ * @param int $attachment_id The WordPress attachment ID.
+ * @return string|false The canonical URL, or false if $attachment_id is not an attachment.
+ */
+function get_attachment_ap_id( $attachment_id ) {
+	$attachment_id = (int) $attachment_id;
+
+	if ( $attachment_id <= 0 ) {
+		return false;
+	}
+
+	if ( 'attachment' !== \get_post_type( $attachment_id ) ) {
+		return false;
+	}
+
+	return get_rest_url_by_path( 'media/' . $attachment_id );
+}
+
 /**
  * Convert a string from camelCase to snake_case.
  *

includes/model/class-blog.php

@@ -419,14 +419,20 @@ public function get_following() {
 	 * @return string[]|null The endpoints.
 	 */
 	public function get_endpoints() {
-		return array(
+		$endpoints = array(
 			'sharedInbox'                => get_rest_url_by_path( 'inbox' ),
 			'oauthAuthorizationEndpoint' => get_rest_url_by_path( 'oauth/authorize' ),
 			'oauthTokenEndpoint'         => get_rest_url_by_path( 'oauth/token' ),
 			'oauthRegistrationEndpoint'  => get_rest_url_by_path( 'oauth/clients' ),
 			'proxyUrl'                   => get_rest_url_by_path( 'proxy' ),
 			'proxyEventStream'           => get_rest_url_by_path( 'proxy/stream' ),
 		);
+
+		if ( \get_option( 'activitypub_api', false ) ) {
+			$endpoints['uploadMedia'] = get_rest_url_by_path( sprintf( 'actors/%d/uploadMedia', $this->get__id() ) );
+		}
+
+		return $endpoints;
 	}
 
 	/**

includes/model/class-user.php

@@ -328,14 +328,20 @@ public function get_featured_tags() {
 	 * @return string[]|null The endpoints.
 	 */
 	public function get_endpoints() {
-		return array(
+		$endpoints = array(
 			'sharedInbox'                => get_rest_url_by_path( 'inbox' ),
 			'oauthAuthorizationEndpoint' => get_rest_url_by_path( 'oauth/authorize' ),
 			'oauthTokenEndpoint'         => get_rest_url_by_path( 'oauth/token' ),
 			'oauthRegistrationEndpoint'  => get_rest_url_by_path( 'oauth/clients' ),
 			'proxyUrl'                   => get_rest_url_by_path( 'proxy' ),
 			'proxyEventStream'           => get_rest_url_by_path( 'proxy/stream' ),
 		);
+
+		if ( \get_option( 'activitypub_api', false ) ) {
+			$endpoints['uploadMedia'] = get_rest_url_by_path( sprintf( 'actors/%d/uploadMedia', $this->get__id() ) );
+		}
+
+		return $endpoints;
 	}
 
 	/**

includes/oauth/class-scope.php

@@ -38,6 +38,13 @@ class Scope {
 	 */
 	const PROFILE = 'profile';
 
+	/**
+	 * Upload access scope - upload media via the uploadMedia endpoint.
+	 *
+	 * @since unreleased
+	 */
+	const UPLOAD = 'upload';
+
 	/**
 	 * All available scopes.
 	 *
@@ -49,6 +56,7 @@ class Scope {
 		self::FOLLOW,
 		self::PUSH,
 		self::PROFILE,
+		self::UPLOAD,
 	);
 
 	/**
@@ -62,6 +70,7 @@ class Scope {
 		self::FOLLOW  => 'Manage following relationships',
 		self::PUSH    => 'Subscribe to real-time event streams',
 		self::PROFILE => 'Edit actor profile',
+		self::UPLOAD  => 'Upload media files',
 	);
 
 	/**