From 28b581b6b1e99d3f76fc4986e387b3c9afdbac69 Mon Sep 17 00:00:00 2001
From: thepra <thepra@pm.me>
Date: Thu, 1 Oct 2026 12:22:08 +0200
Subject: [PATCH] FEDERATION.md and CLAUDE.md describe media, blocks, pins and
 reports

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012CzABvBkbcFqoHdmi8b9WB
---
 CLAUDE.md     | 12 ++++++++++++
 FEDERATION.md | 13 ++++++++++---
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index bfbe211..dd71a04 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -90,6 +90,8 @@ PrivaPub/                         ASP.NET Core Web API, net10.0
     Social/                       FollowService (local in-process, remote Follow/Accept), Notifications
     Timelines/                    Fanout (TimelineEntry rows, Mastodon's home rules), TimelineService
     Privacy/                      VisibilityPolicy (IsPublic expression, CanSee)
+    Relationships/                RelationshipService (blocks, mutes, account domain blocks; Hidden), ReportService
+    Media/                        MediaService (libvips, ffmpeg remux, blurhash), MediaProxy, MediaJanitor
   Domain/Statuses/                StatusService: publish, edit, remove, favourite, reblog, for a persona (both client APIs use it)
   Api/Mastodon/
     Auth/                         OpenIddict setup (keys in Mongo), MastodonScopes, TokenController, OAuthPruner
@@ -190,6 +192,15 @@ cd /var/www/privapub.thepra.dev && sudo -u www-data ASPNETCORE_ENVIRONMENT=Produ
 5. Unsupported features answer empty lists or 422 with a message, never 404 or 500, so clients degrade.
 6. Advertise `4.2.0 (compatible; PrivaPub)` until grouped notifications exist.
 
+## Media invariants
+
+1. **No upload keeps its metadata.** Images are re-encoded by libvips with `keep=none`; audio and video are remuxed with
+   `-map_metadata -1`. `MediaProcessingTests` checks EXIF and XMP are gone.
+2. Files live under `Media:Root` (`/var/lib/privapub/media`), never in the published directory; the proxy cache is the
+   sibling `media-proxy`, which `/media/files` does not serve.
+3. **A client never contacts a remote server for media:** every remote URL the API returns goes through
+   `IMediaProxy.Wrap`, an HMAC-signed `/media/proxy/` URL fetched by `IFederationHttp.GetMedia`.
+
 ## Privacy invariants
 
 - **No root id in federation output, NodeInfo or logs, no IP next to an identity in logs, and no `ex.Message` to a
@@ -199,6 +210,7 @@ cd /var/www/privapub.thepra.dev && sudo -u www-data ASPNETCORE_ENVIRONMENT=Produ
 - **One username space:** personas, groups and the instance reserve their name in `ReservedName` (unique index) before
   they are saved; `LocalActorService.TryReserveUserName` is the only way to claim one.
 - **Per-avatar state stays per avatar:** blocks, mutes, notifications, follows. Nothing may relate sibling avatars.
+- **Blocks never federate,** and reports leave as `Flag` from the instance actor.
 - **Location-ranged posts never federate.**
 
 ## Data
diff --git a/FEDERATION.md b/FEDERATION.md
index 002b044..8199645 100644
--- a/FEDERATION.md
+++ b/FEDERATION.md
@@ -67,9 +67,16 @@ Received:
 | `Like` | counted and notified, on posts the liker could see |
 | `Announce` | counted and notified for local posts; shown to followers of the announcer, with the original refetched from its origin |
 | `Delete` | deletes the object, or the actor and its follows |
+| `Flag` | becomes a report for this server's moderators |
 
 Sent: `Follow`, `Undo{Follow}`, `Create{Note}`, `Update{Note}`, `Update{Person}`, `Delete{Tombstone}`, `Accept{Follow}`,
-`Announce` (communities). A deleted post answers 410 with a `Tombstone`.
+`Reject{Follow}`, `Like`, `Announce` and their `Undo`, `Flag`. A deleted post answers 410 with a `Tombstone`.
+
+- **Attachments** are `Document`s with `mediaType`, `name` (alt text), `blurhash`, `focalPoint`, `width` and `height`.
+  Uploaded files have all metadata removed.
+- **Pinned posts** are the actor's `featured` collection (`/trophies`); `featuredTags` is `/tattoos`.
+- **Blocks are never sent.** A blocked account is sent `Reject{Follow}` if it followed, and is unfollowed.
+- **Reports** are sent as `Flag` by the instance actor, never by the reporting account.
 
 A `Create`'s `Note` carries Mastodon's `content`, `contentMap`, `summary` and `sensitive`, plus `Mention` and `Hashtag`
 tags. A post's title becomes `name` and is also the first, bold line of `content`, because Mastodon does not show
@@ -94,7 +101,7 @@ followers-only posts are recognised by the author's own `followers` collection.
 
 ## Known limitations
 
-- Avatars cannot send likes or boosts yet (that arrives with the Mastodon client API), and media uploads and polls are not
-  implemented.
+- Polls and custom emoji are not implemented.
+- Remote media is fetched through this server's proxy when a local client displays it.
 - Collections expose counts, not members.
 - Only `rsa-sha256`-style keys are verified. RFC 9421 signatures are planned.