SocialPub/CLAUDE.md

CLAUDE.md

Guidance for working in this repository. docs/ROADMAP.md holds the owner's decisions and the phased plan to full ActivityPub interop; read it before changing anything federation-, privacy- or API-shaped. docs/INTEROP.md is the per-platform evidence behind phases P5 to P8: what each peer sends, what it expects, and what PrivaPub still drops. Check the platform's section there before writing a parser or a renderer, and add to it whatever you learn.

What this is

PrivaPub (repo name SocialPub) is a self-hosted ActivityPub server in C#, live at https://privapub.thepra.dev. It is meant as a Pleroma-like microblogging server for privacy-minded people and small communities, federating with Mastodon, GoToSocial, Pleroma/Akkoma, Misskey and Lemmy.

Its defining idea: one private login owns several public personas.

• RootUser is the private login. Username, password, optional email (used only for recovery), policies.
• Avatar is a public persona. Each one is an ActivityPub actor with its own RSA keys at /peasants/{username}. Root and avatar are linked only through RootToAvatar.
• Personas must stay unlinkable to other users and servers; only the instance admin can see the link.
• Group is an ActivityPub Group actor. It has members, an invitation code and an optional password. Groups are becoming two kinds: a public community (FEP-1b12, Lemmy-compatible) and a private, invitation-only circle.
• DmGroup is a direct-message conversation.
• privapub is the instance actor (type Application). It signs fetches no persona should be tied to.

Privacy features in the model:

• location-ranged posts (Post.Location, RangeKm), to become local-only and never federated;
• contacts a persona can share (Avatar.SharedPersonalContacts);
• private notes (RootUserNote, PersonalNote).

The intended client is the Mastodon client API (Tusky, Elk, Phanpy, Ivory), where each avatar logs in as its own account. The private /clientapi covers what Mastodon can't express. thepra/decePubClient (https://decepub.thepra.dev) is the owner's own Pleroma-FE-like PWA. It signs in once on /clientapi and exchanges that JWT for each persona's Mastodon token (PersonaExchange), then uses both APIs.

Route names are deliberate

The odd names are the owner's and part of the project's character. Never "fix" them to conventional ones. A new actor-scoped route gets a name in the same spirit, agreed with the owner, and a name is frozen once it has federated.

Thing	Route
Actor	/peasants/{name} (/users/{name} 301-redirects here; browsers are sent to /@{name})
Inbox	/peasants/{name}/mouth
Outbox	/peasants/{name}/anus (?page=true[&max_id=] for pages)
Shared inbox	/human-centipede (also /peasants/{name}/human-centipede)
Followers	/peasants/{name}/groupies
Following	/peasants/{name}/stalking
Notes	/peasants/{name}/scribbles/{id}
Activities	/peasants/{name}/grunts/{id} (create-{postId} resolves)
DM context	/peasants/{name}/whispers/{id}
Quote permission (FEP-044f QuoteAuthorization)	/peasants/{name}/parrot-licences/{id}
Token refresh	/clientapi/user/sniff/again

Agreed for later phases: /gossip, /drool, /echoes (replies, likes, shares), /trophies (featured), /tattoos (featured tags), /flock and /wardens (group members and moderators).

Routes other software looks up by name stay conventional:

• /.well-known/* and /nodeinfo/*;
• /api/v1/* and /oauth/*;
• /@{name} pages;
• /media/*.

Repo map

PrivaPub.sln
PrivaPub/                         ASP.NET Core Web API, net10.0
  Program.cs                      host, Mongo init (GUIDs Standard), pipeline, /build.json
  Middleware/SocialPubConfigurations.cs   every DI registration (auth, federation, services, swagger, CORS)
  Controllers/ClientToServer/     /clientapi/*: RootUser (signup/login/invitations/recovery), PrivateAvatar,
                                  Group, Post (posts + DMs), Admin, Data
  Infrastructure/
    Http/                         FederationHttp + SafeHttpHandlerFactory + IpRangeGuard: the only way out
    Jobs/                         JobQueue (leases), JobWorker, Backoff, HostCircuitBreaker
    Ids/                          PrivacyIds (day-only ids for personas and groups, arrival-ordered ids for remote posts)
    Data/                         Indexes (created at start), EntityMaps.Warm, Migrations/_NNN_*.cs
    Cli/                          AdminCommands (`PrivaPub admin promote|demote <root>`)
    RateLimiting.cs               accounts (per client address) and inbox (per sending origin) policies
  Federation/
    Controllers/                  PeasantsController (actor, outbox, followers, following, posts, inboxes),
                                  WellKnownController (webfinger, nodeinfo), UsersController (redirect)
    Actors/                       LocalActorService (LocalActor, Keys, ReservedName), RemoteActorService
                                  (authoritative fetch, key verification, WebFinger), ActorDocument (parser)
    Objects/                      Origin, ActivityJson, NoteParser, Addressing, ContentSanitizer
    Moderation/                   DomainBlocks (suspend / silence / reject media)
    Signing/                      HttpSignatures (draft-cavage sign/verify)
    Inbox/                        InboxReceiver (verify, queue, 202) → InboxProcessor (job) → Handlers/{Follow,Accept,Reject,
                                  Undo,Create,Update,Delete,Like,Announce}; RemotePosts (build, fetch parents, FetchAncestors)
    Outbox/                       OutboxPublisher (who a post goes to), DeliveryService (queues jobs) + DeliveryJobHandler
    Rendering/                    ActivityPubRenderer (Mastodon @context, actors, notes, collections)
  Domain/
    Content/                      ContentRenderer (Markdown or plain text → HTML with h-card mentions and hashtags)
    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
    Infrastructure/               MastodonController (avatar context, scopes, errors, Link), MastodonParams, MastodonJson, Page
    Entities/ Mappers/            Mastodon entities; MastodonMapper (Account, Status), AccountSearch
    Controllers/                  apps, instance, accounts, statuses, timelines, notifications, search, stubs
  Web/Pages/                      Razor: /@{user}, /@{user}/{id} (public posts only, strict CSP, noindex);
                                  OAuth/: /oauth/login (root password), /oauth/authorize (choose persona, consent)
  Services/                       RootUsersService, GroupUsersService, PostsService, AppConfigurationService, …
  Models/                         Mongo entities: User/, Group/, Post/, Federation/, Jobs/, AppConfiguration
  StaticServices/                 DbEntities (Find<T> accessors), AuthTokenManager (JWT), PasswordHasher
  Data/InitDb.cs                  first-run seeding (languages)
PrivaPub.ClientModels/            DTOs + validation resources shared with clients
PrivaPub.Tests/                   xUnit v3; Support/ has a fake two-origin peer and a throwaway-database fixture
deploy/                           nginx vhost, systemd units (privapub, privapub-mongod), max/setup.sh
.gitea/workflows/                 build.yml (push) · deploy.yml (tag v*)
docs/ROADMAP.md                   decisions + phased plan

The roadmap moves code towards Infrastructure/, Federation/, Domain/, Api/{ClientApi,Mastodon} and Web/, one pure-move commit at a time.

Commands

dotnet build PrivaPub.sln -c Release
dotnet test PrivaPub.sln                                  # unit tests; integration tests skip
PRIVAPUB_TEST_MONGOD=1 dotnet test PrivaPub.sln           # all of them, against mongod on 127.0.0.1:27017
                                                          # (PRIVAPUB_TEST_MONGO overrides; a fresh database per run, dropped after)
tools/ci/with-test-mongod.sh dotnet test PrivaPub.sln     # all of them, on a throwaway mongod, as CI runs them
cd PrivaPub && ASPNETCORE_ENVIRONMENT=Development \
  Kestrel__Endpoints__Http__Url=http://127.0.0.1:6970 Kestrel__Endpoints__Http__Protocols=Http1AndHttp2 \
  AppConfiguration__BackendBaseAddress=http://127.0.0.1:6970 MongoSettings__Database=PrivaPubTest \
  dotnet run                      # needs a local mongod on 27017; swagger at /swagger

Development config (appsettings.Development.json) binds HTTPS 7195 with HTTP/2 only; the overrides above make it curl-able. Outbound fetches only go to https DNS names resolving to public addresses; a test network (Pasture) sets Federation__AllowPrivateNetworks=true, Federation__AllowPlainHttp=true and Federation__AcceptAnyCertificate=true, which startup refuses in Production.

The admin CLI runs with every service built but nothing started (no Kestrel, no hosted services), so it can run next to the live service. Sign-up is closed in production (invitations only), so the first login is made here; promoting is how an admin is made (signing up as "admin" grants nothing):

cd /var/www/privapub.thepra.dev
echo '<password>' | ASPNETCORE_ENVIRONMENT=Production ./PrivaPub admin create-root <login> --admin   # password on stdin
ASPNETCORE_ENVIRONMENT=Production ./PrivaPub admin promote|demote <root>
ASPNETCORE_ENVIRONMENT=Production ./PrivaPub admin smoke <persona>     # the deploy's: prints "deploy-smoke <new password>"

The deploy runs them as build-runner, which owns the published files, reads appsettings.Production.json through group www-data and reaches the private mongod; sudo -u www-data works too.

Federation invariants

1. Every outbound request goes through IFederationHttp. Its handler resolves the name itself and connects only to public addresses; redirects are followed by hand (three at most, each re-checked); bodies are capped at 1 MB; only JSON media types are read; a refused URL is not asked again for five minutes. Never create another HttpClient for federation. The only other outbound traffic is SMTP and GeoUpdater's monthly DB-IP Lite download (its own geo client, a fixed HTTPS host, size-capped, the file checked before it is swapped in).
2. Every fetch is signed by the instance actor (privapub), never by a persona; deliveries are signed by the acting avatar or group. Both are draft-cavage rsa-sha256 over (request-target) host date (+ digest on bodies).
3. A remote document is believed only from its own address. RemoteActorService.FetchObject requires the document's id to be the URL it was served from (a same-origin alias is followed once). A key is accepted only if the actor lists it, its owner is the actor and it shares the actor's origin.
4. Inbound inboxes verify everything before acting:
   • the signature covers (request-target), host, digest and date or (created);
   • the Digest matches the body and the date is at most an hour old and fifteen minutes ahead;
   • the signature verifies against the key owner's key, and the activity's actor is the key owner;
   • the activity's id, and any object it creates, updates or deletes, is on the actor's origin; a cross-origin object is refetched from its own origin.
5. Status codes:
   • bad or missing signature: 401;
   • malformed or forged body: 400;
   • accepted: 202;
   • over the rate limit: 429;
   • never 500 from /peasants or an inbox. Peers retry or "double-knock" based on these codes.
6. Actor documents:
   • served as application/activity+json;
   • publicKey is an SPKI PEM at {actor}#main-key, with owner equal to the actor's id;
   • the shared inbox is advertised in endpoints.sharedInbox.
7. Remote HTML is sanitized before it is stored (ContentSanitizer); Post.ContentHtml is what is shown, ContentFormat says what Text holds. Remote names are plain text.
8. Circles federate to members only. A circle is an undiscoverable Group actor that takes follow requests (the owner approves); its posts are addressed to the circle and its /flock, delivered to members' personal inboxes, never announced. Each member's copy also names that member in cc (OutboxPublisher.Naming, owner decision 2026-10-04), because Mastodon and GoToSocial keep a post only when it names one of their accounts; Create, every Update and the Delete all go through OutboxPublisher.Publish for that. A reply to a circle post stays in the circle, and a circle post never asks a non-member for a quote. Circles never appear in search, lookups, mentions or profile pages. A post that is not public is served only to a signed request from someone it was for (SignedFetchAuthorizer.MayRead): a follower or an addressed account for followers-only, an addressed account for a DM, a member for a circle, or the instance actor of a server where one of them lives; 404 to anyone else, 410 to them once it is deleted. A circle refetch names the requesting member, or the members on the requesting server. A DM's context (/peasants/{name}/whispers/{id}) lists the conversation's posts for its participants. Mastodon deletes its copy when a refetch answers 404, which is why this matters. Communities are FEP-1b12 groups: GroupDistributor announces the whole activity (plus the object for new posts, for Mastodon), top-level posts are Pages with a name, posting follows Group.PostingPolicy. Located posts (LocalGeo) are the only local-only posts.
9. A DM joins a conversation only by DmGroup.ParticipantsKey, the exact set of its participants; a remote context decides nothing. DMs are Posts with Visibility = Direct and a ConversationId (DmPost is legacy).
10. Nothing slow happens inside a request. Deliveries and inbox processing are Jobs (Infrastructure/Jobs): leased, retried on Mastodon's curve, at most two per host, paused per host by RemoteInstance. The inbox answers 202 once it has verified and queued; a handler must be idempotent (unique ObjectURI, job DedupeKey).
11. Every number about posts and users goes through Domain/Privacy/Counted (owner decision 2026-10-04: one answer everywhere): a persona's statuses_count, its outbox totalItems, NodeInfo localPosts and the instance status_count all count Mastodon's way (not deleted, not a DM, boosts included, circle and located posts too); users exclude personas of banned or deleted roots; replies_count counts only public and unlisted replies; a remote account that deletes itself takes its likes, votes, reactions, boosts and replies out of every count (GoneActors). Follower and following counts are public, their members never are (hide_collections is always true).
12. Every "may anyone see this" goes through VisibilityPolicy.IsPublic; a persona-specific read uses CanSee, and any other read of stored posts filters by IsShown. All three hide deleted posts and the posts of a remote account that deleted itself (Post.AuthorGone: kept, hidden everywhere, owner decision).
13. Remote content is stored only when someone here asked for it: a persona follows the author, is addressed or mentioned, it replies to a local post, or it is addressed to a community the author follows; a public parent is fetched as context. Followers-only is detected by the author's stored followers URL.
14. Home timelines are written, not computed: every stored or created post goes through Fanout.Distribute, and every delete removes its TimelineEntry rows. Local deletes are soft (content cleared, 410 Tombstone).

Mastodon client API invariants

1. A token is one persona. Its subject is the avatar id; the root id lives only in the fifteen-minute /oauth cookie used while choosing the persona, and never in a token, an authorization or a response.
   • The first-party client exchanges the root JWT for one persona's token (RFC 8693 on /oauth/token, subject_token_type urn:ietf:params:oauth:token-type:jwt, avatar_id; Api/Mastodon/Auth/PersonaExchange.cs). Only the seeded public application (ClientApi:FirstPartyClientId, default decepub) holds the grant. RootJwtSubjectToken validates the JWT through RootJwt, the same rules as JwtBearer (signature, lifetime, ban, deletion, session stamp). The issued token is the same kind as the authorization code flow's, so revocation and RootSessions cover it.
2. /api/* authenticates with OpenIddict validation, everything else with the old JWT (PrivaPub policy scheme). Every /api request re-checks that the persona's root is neither banned nor deleted (MastodonController).
3. Read parameters through Params (query, form and JSON merged Rails-style), never MVC binding. A value type read from a conditional must say (int?)null, not default: that bug once made every list one item long.
4. Answer with Json(...) (snake_case, explicit nulls) or Error(status, message); page lists with Page and Link.
5. Unsupported features answer empty lists or 422 with a message, never 404 or 500, so clients degrade. Any /api error that leaves without a body (a challenge, a 404 from routing, a 429) gets Mastodon's {"error": ...} from UseMastodonErrorBodies. NeverFiveHundredTests walks every route with junk ids, anonymously, as a persona and with a junk token.
6. Advertise 4.2.0 (compatible; PrivaPub) until streaming and Web Push exist too; api_versions.mastodon = 7 stays, because clients show quotes from it, so everything a 4.3+ client calls because of it must answer: grouped notifications (/api/v2/notifications, its unread count, groups, accounts and dismiss) and the notification policy.
7. What a Mastodon Status cannot say goes in Status.privapub (PrivaPubStatus): object type, title, excerpt, cover, the author's source, link, video, audio and event details, and up/down votes. Every media URL in it goes through the proxy; only page links (link.url, an event's online link) point at the remote site, because following one is the reader's choice.

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.

4. The proxy serves three ways:

   • Cached: a file already cached is served from disk, ranges included.
   • Downloaded: a request without a Range is downloaded whole, up to Media:MaxProxiedBytes, then cached.
   • Streamed: a ranged request, or anything too big to cache, is streamed from the origin with the range passed on, and never cached. That is how remote video plays.

   nginx has a /media/proxy/ location with proxy_buffering off and a 600 s read timeout for those streams.

5. Remote video and audio become one playable attachment in the Mastodon API (MastodonMapper.Playable): the best MP4 up to 720p that carries both sound and picture, including PeerTube's fragmented files inside an HLS entry. HLS playlists themselves are not rewritten.

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 client ("Something went wrong." instead).
• Sign-in and recovery never tell which logins or addresses exist (owner decision 2026-10-04): every failed sign-in gets "That username and password do not match." after the same hashing (RootUsersService.Decoy, a constant-time comparison), and only a correct password learns of a ban. Every recovery request answers the same sentence and queues a SendRecovery job, found or not; RecoveryJob sends the email and keeps only a SHA-256 of the code, for an hour. A recovered password ends every session of the root (RootSessions: a new SessionStamp, which every /clientapi JWT carries, and OpenIddict revocation for each persona).
• Deleting a root deletes everything public it had (RootRemoval, from the admin route or /clientapi/user/delete with the password): its sessions end, each persona and each group it owns sends Delete{Actor} to followers, members and the accounts it follows, the personas' posts are emptied, and /peasants/{name}, its inbox and WebFinger answer 410 (LocalActorService.Gone) while the names stay reserved. The root keeps only a deleted-{id} name.
• Never derive a public name from the root username. Invitation sign-up takes AvatarUserName and refuses one equal to the login.
• 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.
• Usernames are Constants.UserNameRegex (^[a-z0-9_]+$): the intersection of what Mastodon and Misskey accept. A name outside it creates a persona nobody on those servers can reach.
• An actor's published is PublishedOn, a random whole day up to two weeks before creation, so personas made the same day do not share a date. New persona and group ids carry that same day (GenerateNewID), because local clients see ids. Never emit CreatedAt.
• Per-avatar state stays per avatar: blocks, mutes, notifications, follows. Nothing may relate sibling avatars.
• Blocks federate (owner decision, 2026-10-01): a block is sent as Block from the blocking avatar, an unblock as Undo{Block}. Reports still leave as Flag from the instance actor, never from the reporting avatar.
• What PrivaPub reveals is the owner's call. Previews, blocks, website authorship, views, bridging and reactions were decided in docs/ROADMAP.md ("Owner decisions on what PrivaPub reveals"). Anything new that tells another server something about an avatar gets the same treatment: ask, then record it there.
• Location-ranged posts never federate.
• Statistics name servers, never people (owner decisions on statistics, 2026-10-03). Every interaction is recorded through IInteractionLedger (Infrastructure/Statistics) as an InteractionEvent (90 days), but an event never holds a root, persona or group id, an activity id, an inbox URL, a remote actor URI or a sender IP:
  • Distinct remote accounts are counted with ActorHash, an HMAC keyed by that day's InteractionSalt, which the day's rollup deletes.
  • LocalKind survives Interactions.Sanitize only on public and unlisted traffic, so a circle can show neither by presence nor by absence, and no reason code names one.
  • Traffic a reader causes (the media proxy, lookups, the client API, fetches of our own documents) is only counted per day (Count, CountServer), never logged per event.
  • A host claimed by an unverified sender is kept only if it is already a RemoteInstance.
  • Record never blocks and never throws: it writes to a bounded channel, and a full channel drops and counts.

Data

• MongoDB through MongoDB.Entities 25.1, instance API: DB.Default.Find<T>(), .SaveAsync(e), .Update<T>(), .DeleteAsync<T>(), .CountAsync<T>(). DbEntities wraps the finds.

• Pass no cancellation token to DeleteAsync outside a transaction; v25 throws if you do.

• Collection name = class name, so never rename an entity class.

• Entity.ID is a 24-character lowercase hex string; GenerateNewID() returns object, so cast it.

• New fields must be additive: a deploy rollback restores the binary, not the database.

• Every stored remote object has an ObjectRecord (raw JSON up to 256 KB plus its hash; delivered or fetched; the activity, inbox, key and signed headers; received time; up to 10 later revisions). Write it right after the post's save: CreateHandler (delivered) and RemotePosts.StoreContext (fetched) do, and UpdateHandler appends a revision. Delivery details reach them through Arrival.Current, which InboxProcessor sets for the handler's duration. A fetched record has no signature, key or @context of the activity that caused the fetch (its activity fields name that trigger), and every record stores its Extensions and ContextNamespaces for statistics. The raw form lives outside Post so timelines never load it. Read through /api/privapub/v1/statuses/:id/provenance and /api/privapub/v1/instances/:host.

• Remote objects are parsed for every shape in ObjectShapes: url/icon/image as a value, an object or an array; Markdown content; missing mediaTypes inferred; thumbnails from any of their five places; and the typed Link, Video, Audio and Event details. A Mastodon API card is built from those, never by fetching the linked page (that fetch is the owner's decision 1, for P6).

• An Update is an edit only when its updated is newer than ours, or for a first edit no older and with the text actually changed, since GoToSocial's whole-second timestamps make a quick edit carry updated == published (RemoteEdits.IsEdit; plain and community-wrapped Updates both go through RemoteEdits.Apply, and deletes through RemoteDeletes.Remove). Otherwise it refreshes the poll, video, audio and event details and nothing else, and leaves no revision: Mastodon and Misskey refresh poll counts with bare Updates.

• A poll vote is a Note with a name, an inReplyTo that is a poll we hold, and no content. CreateHandler hands it to PollService.Receive before anything else, so it never becomes a reply. Our votes on other servers' polls go only to the poll's author, without published (PieFed counts a vote only then). A closed in the future is the poll's end, not its closing: Akkoma sends an open poll's end only there (ObjectShapes).

• Link previews follow owner decision 1 (Domain/Content/LinkPreviews.cs): only public posts, queued on arrival with 0–60 s of jitter, one cached LinkPreview per address for the whole server, never fetched when someone reads. LinkPreviews.Wanted is called where posts are saved (CreateHandler, StoreContext, StatusService.Publish).

• Quote states come from QuoteService.Resolve:

  • with a stamp: accepted only if Verified (fetched, on the quoted author's origin, naming both posts exactly);
  • a FEP-044f quote without a stamp: pending;
  • older keys only: accepted when the quoted post is public.

  QuotesCount moves with the accepted state, never with the raw key. When a persona quotes, QuotePermission decides: asking first for posts that state a policy, quoting at once for posts that state none, refusing otherwise. Only quote of a post that asks for consent puts quote in our JSON; older-key quotes leave it out, as Sharkey learned they must.

• Our quote policy is ActivityPubRenderer.QuotableBy: the post's LocalQuotePolicy, falling back to the persona's Settings.QuotePolicy (default public, owner decision), and always nobody for anything but public and unlisted. The same rule writes canQuote, answers QuoteRequests (QuoteService.ReceiveRequest) and fills quote_approval, so they cannot disagree. A persona quoting another persona gets a parrot-licence too, so other servers see an approved quote.

• A server is described on arrival, never on read. The first record from a host enqueues DescribeInstance (its NodeInfo, at most once a week, into RemoteInstance), so opening the details view tells nobody anything.

• Post ids are the timeline order, so they follow arrival, not published. PrivacyIds.Arrived gives a remote post published within the last hour (or in the future) a fresh ObjectId, which sorts after every post already stored, and only backfill keeps a published-derived id. With published ids a reply arriving in the same second could sort under the post it answers, and a late arrival landed behind a client's since_id and was never seen. created_at comes from CreationDate, never from the id.

• The same ordering problem exists on the other side, so published carries milliseconds (ActivityPubRenderer.Timestamp). GoToSocial (ULIDs) and Mastodon (Snowflakes) derive a remote status's id from published at millisecond resolution. With whole seconds, two of our posts from the same second sorted at random there.

• Startup order: EntityMaps.Warm() (every entity's class map, one at a time; two mapped at once throw "An item with the same key has already been added" and stay broken), then MigrateAsync (Infrastructure/Data/Migrations, _NNN_ order, each runs once), then Indexes.Create(). A new entity needs nothing; a new unique index needs a dedupe migration before it.

• Production runs its own mongod on 127.0.0.1:27022 (unit privapub-mongod, no auth, data in /var/lib/privapub/mongo). The box's shared mongod needs credentials nobody here has.

Code style

• Tabs, block-scoped namespaces, Allman braces.
• New services use readonly _camel fields and constructor injection. Older services use PascalCase fields; leave them.
• Services return WebResult (PrivaPub.ClientModels/WebResult.cs): result.Invalidate(localizer[...], status). Controllers turn it into a status code.
• Localised strings go through IStringLocalizer<GenericRes>.
• Every Display/ErrorMessage resource key must exist in FieldsNameResource/ErrorsResource, including the Designer.cs, which the CLI build doesn't regenerate. A missing key throws at validation time.
• cond ? value : default with a value-type branch is the type's default, not null: false, 0, or year one stored as an edit date on every remote post. Write (T?)null. It has shipped four times (MastodonParams.Bool/Int, NoteParser.Int, NoteParser.Time).
• ActivityPub output is built with System.Text.Json.Nodes in ActivityPubRenderer, not typed models. Inbound documents are read through ActivityJson.Id/Value, which handle string, object and array.
• Libraries chosen for the roadmap: HtmlSanitizer, Markdig (DisableHtml), NSign (RFC 9421 inbound), OpenIddict + OpenIddict.MongoDb, NetVips, Blurhash.Core, FFMpegCore. No ImageSharp (licence key enforced), no MassTransit.

Testing

PrivaPub.Tests (xUnit v3). Unit tests need nothing; tests marked Category=Integration need a mongod and skip without PRIVAPUB_TEST_MONGOD=1. CI (build.yml and deploy.yml) runs all of them through tools/ci/with-test-mongod.sh, which starts a throwaway mongod on a random localhost port and deletes it afterwards. The box's own mongods are production, so MongoFixture refuses port 27022, a data directory under /var/lib/privapub, and in CI anything but the wrapper's mongod. With PRIVAPUB_TEST_REQUIRE_MONGOD=1, which the wrapper sets, a missing mongod fails the run instead of silently skipping half the tests.

• Support/Peer is an in-process HTTP server answering on two origins (127.0.0.1 and localhost), so origin rules can be tested; Support/RemoteActor signs real deliveries with its own key.

• Inbox scenarios go through InboxReceiver.Receive with a signed request, not through the private handlers.

• Support/Host/PrivaPubHost is the whole server under test (WebApplicationFactory<Program>, environment Testing, configured only through UseSetting, on the fixture's database). PrivaPubHost.Shared() boots it once per run; SecureModeHost is the same with Federation:SecureMode. Background workers are removed, so a test runs the jobs it queued with host.Run(j => ...) or host.RunInbox(activityId). Accounts signs a root up, adds personas, and gets a Mastodon token through the real /oauth code flow; RemoteActor.SignedPost/SignedGet sign HttpRequestMessages for the real /peasants routes. Each client gets its own X-Test-Client address, so rate limits don't collide.

• All test classes share one database and run in parallel, so a test touches only rows it made:

  • random names and GUIDs;
  • Harness.Outgoing sees only deliveries queued since that harness started, because Peer ports are reused;
  • a worker gets a scoped new JobQueue(j => ...) so it never leases another test's jobs;
  • domain blocks are set with DomainBlocks.Load, never written to the database.

  A test that must change something database-wide (drop indexes, run a migration over every post, let deliveries to localhost fail and trip its breaker) goes in [Xunit.Collection(nameof(Exclusive))], which runs alone, and cleans up after itself. Pure logic belongs in an unconditional unit test, not in a Mongo-gated class.

Beyond the tests, verify by building, running locally, and exercising:

• the client API (sign up, create an avatar, a group, a post);
• the ActivityPub endpoints with curl and Accept: application/activity+json.

Interop is checked against real servers, starting with the workstation's own pasture:

DOTNET=~/.dotnet/dotnet tools/pasture/run.sh up [gts mastodon ...]   # podman: PrivaPub + the named peers (default gts) + Mongo, behind Caddy
tools/pasture/interop.sh [gts mastodon ...]                          # each peer's scenario, then what PrivaPub's statistics saw of it
tools/pasture/run.sh down                                            # removes every pasture container and volume

• Layout: lib/pasture.sh (network, Caddy, Mongo, PrivaPub), peers/<name>.sh (<name>_up, plus peers/shared.sh for the Postgres and Redis several peers share), lib/interop.sh (ok, ko, xf for a check expected to fail until a later phase, privapub_token <persona>, stats_check <host> <software>), scenarios/<name>.sh. Each peer talks to its own PrivaPub persona under one root, so OAuth's persona choice is exercised too. Images are pinned.

• Caddy's CA lives in the pasture-caddy-data volume and is copied to tools/pasture/.ca/root.crt (and bundle.pem with the system roots) for peers that must trust it instead of skipping verification.

• All sites on one podman network, one Caddy in front. privapub.test, gts.test, mastodon.test and the other peers are network aliases of the Caddy container, which serves them all with its internal CA (tls internal). PrivaPub accepts any certificate (appsettings.Pasture.json) and GoToSocial is told to skip verification (GTS_HTTP_CLIENT_TLS_INSECURE_SKIP_VERIFY); Mastodon trusts the copied CA through SSL_CERT_FILE. Peers fetch over https only, so plain http between them is not an option.

• From the workstation, PrivaPub's API is http://127.0.0.1:6971. A peer is reached as https://<name>.test:6443 with curl -k --resolve <name>.test:6443:127.0.0.1, because sign-in cookies are bound to the host name.

• GoToSocial (0.22.1):

  • Its cached home timeline can stop taking new posts after its first read, its owner's own included, while a min_id query shows them all. So a delivery is checked by looking the object up by URI with resolve=false (on_gts), which answers from GoToSocial's database and never fetches from us. A home-timeline check there proves nothing, in either direction. A deleted status still turns up in that search as a "deleted status" stub, so a delete is checked as a 404 on /api/v1/statuses/{id}.
  • It creates its accounts locked, so the scenario approves alice's request through /api/v1/follow_requests, which also checks our pending (requested) state and the manual Accept.
  • 55 checks: discovery and follows both ways; posts and CW; a reply and its notification; likes and boosts both ways; DMs both ways and off public timelines; polls both ways; quote policy; link cards; edits and deletes both ways; communities and circles; locked personas; unfollow; block and unblock; statistics.
  • It files a circle post as a direct message and shows it only to the accounts it mentions, so like a DM it is checked in the member's /api/v1/conversations, never by URI.

• Mastodon (4.7.3): web and sidekiq on the shared Postgres and Redis, ALLOWED_PRIVATE_ADDRESSES for the network. Its token comes from rails runner (no password grant). Without Elasticsearch its status search finds nothing, so deliveries are checked through /api/v1/accounts/:id/statuses of the sender as Mastodon knows them, or Status.exists? through rails runner. Its actors are numbered (/ap/users/<id>), so look URIs up rather than build them. Circle posts and a followers-only post survive its signed refetch (ActivityPub::FetchRemoteStatusService through rails runner). Inbound Block is the one expected failure until P7.

• Misskey (2026.10.0): one container on the shared Postgres and Redis. A new Misskey federates with nobody (federation: none) until admin/update-meta says all, which misskey_up does. Its API is POST /api/<endpoint> with the token as i (mk in the scenario); users/relation answers a list, users/notes leaves replies out unless asked, and a user has one reaction per note. Never verify a delivery with ap/show: it fetches. 35 checks.

• Sharkey (2025.4.7): peers/sharkey.sh is the Misskey peer under another name, image, database, Redis db and home (/sharkey/.config); scenarios/sharkey.sh runs Misskey's scenario with MISSKEY_NAME=sharkey, then follows again (Misskey's ends unfollowed and blocked) and checks edits both ways and the FEP-e232 quote tag. 40 checks.

• Akkoma (3.20.1): no official image, so images/akkoma installs the OTP release (pinned by checksum; the "stable" zip moves, and a moved one fails the build) and akkoma_up builds it once. Its HTTP clients read the CA bundles shipped in the release (CAStore, certifi), so the entrypoint appends Caddy's CA there. pleroma_ctl passes its arguments on unquoted: no value may contain a space. Its Linkify never takes @user@host.test for a mention, so the scenario addresses alice with Pleroma's to[]; its API never reports a remote blocker as blocked_by, so the block is read from its user_relationships. 44 checks.

• Lemmy (1.0.0-beta.2): the backend alone on the shared Postgres, its admin made by setup in the generated config.hjson. It trusts Caddy's CA through SSL_CERT_FILE and reaches the network through DANGER_FEDERATION_ALLOW_LOCAL_IP=1; 0.19 cannot join (its rustls trusts only its bundled roots). Its API is /api/v4/<path> with a bearer token (lm in the scenario), and sort values are lowercase. It logs no refused activity at warn (LEMMY_LOG sets RUST_LOG); the reason is in the 400's body. It answers our community's echo of its own activity and every bare Announce{object} 400 by design, and the echo is still needed (see docs/INTEROP.md, Lemmy). A new Lemmy never sends what it queued for a server before its send worker for that server started, so the scenario waits for that worker (lm_worker) before its first follow. 20 checks; relayed votes and a moderator's removal are expected failures (P7).

• SecureMode: PRIVAPUB_ENV="Federation__SecureMode=true" run.sh up …, as production runs. A check of what an unsigned reader sees uses unserved and gone_unsigned (lib/interop.sh), which expect 401 when SecureMode is on and 404 or 410 when it is off.

• Crawler: PRIVAPUB_ENV="Statistics__Crawler__Enabled=true Statistics__Crawler__Seeds__0=mastodon.test" run.sh up mastodon, then interop.sh crawler. PRIVAPUB_ENV passes any setting to the PrivaPub container.

• run.sh up replaces every container, Mongo included, so each run starts clean. To keep the data, republish into tools/pasture/.publish and podman restart pasture-privapub; that is how a migration is tried on dirty data.

After the pasture, verify.funfedi.dev and the owner's GoToSocial at social.arasaka.software. Ask before acting from the owner's GoToSocial account.

Deploy

• CI/CD: push to master runs build.yml (build + tests) on the instance-wide build runner. A v* tag runs deploy.yml: tests, self-contained linux-x64 publish, snapshot and mongodump to /var/backups/privapub.thepra.dev, stop → rsync → start, a 127.0.0.1:6970/build.json health loop with rollback, then public checks (actor, NodeInfo, Swagger 404, inbox junk 400, unsigned 401) and tools/smoke/mastodon-api.sh (app registration, client credentials, discovery, instance, public timeline). Then it checks that what production should be running is running:
  • NodeInfo and the instance API agree on registrations (closed, invitations only);
  • /stargazing says the crawler is on;
  • @thepra signs in: PrivaPub admin smoke thepra gives the root deploy-smoke a new password, tools/smoke/oauth.sh runs the real OAuth flow (the pasture's privapub_token uses the same script), the signed-in API is checked, the persona must be undiscoverable, and the token is revoked;
  • the DB-IP Lite databases, which the server fetches itself (GeoUpdater), exist and are at most 40 days old.
• The box: Max (nuvola.xyz). Unit privapub runs as www-data from /var/www/privapub.thepra.dev with ASPNETCORE_ENVIRONMENT=Production.
• One-time root setup: deploy/max/setup.sh, run through ../arasaka.software/tools/max/run.sh (directories, the runner's sudoers line, the units, nginx and the certificate). Nothing that runs later needs it again.
• Config: appsettings.Production.json is committed and deployed, secrets included, by the owner's convention (the same as arasaka.software). A hand edit on the box is lost at the next deploy.
• Secrets drift: AppConfigurationService copies AppConfiguration into Mongo on first boot and reads the stored copy afterwards, so changing those keys needs a Mongo update as well.
• Logs: journalctl -u privapub, plus the logs database on the private mongod.