ActivityPub defines two protocols. The server-to-server (S2S) protocol supports server federation. The client-to-server (C2S) API, which the specification calls the Social API, lets an authorized client act on a server on behalf of an actor. The Social API has client-side and server-side requirements. All are defined by the same W3C Recommendation, published in January 2018.
The ActivityPub federation protocol is the only one that is currently in wide use. However, C2S has found few implementations. The ActivityPub C2S Toolkit exists to help C2S server developers by providing browser-based tools for testing and debugging. It does not provide client-side testing support. The advantage of a browser-based tool is that common issues, like Cross-Origin Resource Sharing (CORS) problems, are detected where they often go unnoticed with non-browser tools. The toolkit sits alongside the standardization work now under way in the Social Web Incubator Community Group (SWICG).
The Toolkit
The toolkit is a web-based development tool for testing and debugging ActivityPub servers that implement the C2S API, built as a Vue 3 single-page application. It speaks to the target server directly over that API. No intermediary service holds the credentials or rewrites the requests, so each request the tool issues is one the server would receive from any other C2S client, which is what makes its results meaningful. Apart from an optional sidecar for diagnosing CORS issues, the application has no backend of its own: the production build is a set of static files that can be served from anywhere.
It is not a social client. This is a tool for developers to test server implementations, not for end users interested in microblogging or image sharing.
Tool Design
The core toolkit runs entirely in the browser. Nothing has to be installed besides the server under test. The tool lives inside the browser's security model. The browser can intentionally obscure certain issues related to CORS, which is a common server issue. This is why the project ships an optional CORS sidecar. This allows the toolkit to diagnose hidden CORS problems.
Diagnostics take precedence over convenience. A conventional client hides the authorization flow behind a redirect and a login form. The toolkit displays each OAuth 2.0 step with its inputs and outputs, because the user is establishing where the flow broke rather than trying to get through it quickly.
The tool supports several authentication flows and variations. For example, servers may use different methods for authorization server discovery, so the toolkit supports Client ID Metadata Documents (CIMD), RFC 9728 protected resource metadata, bearer tokens supplied with no flow at all, and Mastodon's legacy OAuth2 implementation. These auth flow variations are detected automatically. Inspection of response payloads follows the same principle: raw JSON, object previews, and object actions replace a single rendered interpretation. Auth flow diagnostics, payloads, and automated test results can be exported as JSON data and can be used to generate human-friendly reports.
Key Features
A session begins with authorization. The toolkit runs an OAuth 2.0 authorization against the target server with each step and its response left visible, which is the difference between reading a specification and watching a server follow it. For servers that require CIMD, it serves the bundled client metadata document, which must be edited to match the client credentials. Discovery through RFC 9728 protected resource metadata covers servers that publish it. A bearer-token mode handles the case where the authorization flow itself is not the obstacle under investigation, and Mastodon's legacy OAuth2 implementation covers servers that never adopted newer discovery.
Once authorized, the tool locates the actor. It offers several discovery methods because server techniques differ, where the server identifies the actor at all. The inspection tools then take over. A JSON browser walks an ActivityPub object graph as the server returned it. Object previews and actions allow a returned object to be read and acted on without leaving the tool. NodeInfo and WebFinger lookups cover the server metadata that surrounds the client API.
Posting is handled through resource templates. A schema-driven form editor derives its fields from the resource schema, and a JSON template editor performs the same task for authors who prefer writing the document rather than filling a form. The latter also supports server-specific features or invalid documents for error-handling tests. Both techniques produce activity documents that can be posted to the server. Media upload is supported as well, although that implementation follows a W3C wiki discussion that has not been settled, so server implementations vary.
The automated testing side is where the toolkit departs from a manual console. An embedded test framework runs checks against the server and produces a capability report with results attached to each one. That report states what a server does, and exported data makes reports comparable across servers and over time.
Limits, status, and roadmap
As stated earlier, the toolkit is not a general-purpose client. There is no timeline and no reading experience, and no attempt to match the feature set of a Mastodon (or similar) application. The project remains under active development, so the report format and the test set should be expected to change.
Two items sit on the roadmap: pluggable ActivityPub object previews and actions, and the creation of tests from resource templates.
The ActivityPub API Task Force
Standards work on the client API has a home. The ActivityPub API Task Force of SWICG works on the read-write ActivityPub API, with the stated goal of an ecosystem in which client developers build applications on the API and server developers support it. As the task force recommends extensions to the ActivityPub Client API become relatively stable, testing of related features may be added to the toolkit.
Getting started
The repository is at https://github.com/steve-bate/activitypub-c2s-toolkit. It uses the MIT license. Directions for installing and running the toolkit are in the repository's README.md.
Acknowledgement
Development of the toolkit was partially supported by a grant from the NLnet Foundation's Open Social Fund, as part of the ActivityPub PWA project.