Mastodon-compatible Client API subset for @dwk/activitypub (real client login: notifications, timelines)

[davidwkeith]

Package(s) affected

@dwk/activitypub (possibly a new package, e.g. @dwk/mastodon-client-api, if it doesn't fit inside the endpoint package itself — see composition-contract question below).

Problem

Surfaced during the Pixelfed manual conformance run (fediverse interop #273):
after liking and replying to a post from a real Pixelfed account, there was no
way to confirm those activities landed in the actor's inbox — the S2S /inbox
route is write-only by design, and the only read path today is @dwk/mcp's
agent-facing activitypub_list_inbox tool (which the conformance-target
deployment doesn't even mount).

What a real user of @dwk/workers actually wants is simpler and more direct:
log in with the Pixelfed (or Mastodon, or any Mastodon-API-compatible)
client app of their choice and see their own feed/notifications — the same
experience they'd get running an actual Mastodon or Pixelfed instance.

This is explicitly out of scope today. spec/fediverse-interop.md's non-goals
section says:

Platform client APIs (Mastodon REST API, Lemmy HTTP API). Clients speak
micropub/MCP/outbox to this Worker; only federation is multi-platform.

That's the right call for the federation-interop work @dwk/activitypub
currently does, but it means there is currently no way for a site owner to
browse their own notifications/timeline with an off-the-shelf fediverse
client app — only via a custom MCP-connected agent, or by reading the DO's
storage directly.

Proposed solution

Implement a minimal subset of the Mastodon-compatible Client API sufficient
for a real client app (starting with Pixelfed's own web/mobile client, since
that's the platform this was discovered against) to authenticate and show:

• App registration (POST /api/v1/apps) and OAuth authorization/token
  exchange, layered on @dwk/oauth's existing RFC 8414/7591 building blocks
  rather than reinventing OAuth.
• GET /api/v1/accounts/verify_credentials (identify as the one actor this
  deployment serves).
• GET /api/v1/timelines/home and/or /api/v1/notifications — read-only,
  backed by the same DO storage activitypub_list_inbox already reads.
• Explicitly not in this first cut: posting through the Client API
  (micropub already covers publish), streaming, multi-account support (v1 is
  one actor per deployment, same as the rest of @dwk/activitypub), or any
  Mastodon feature beyond what's needed for read-only timeline/notification
  browsing.

Open design questions to resolve before implementation:

• Does this live inside @dwk/activitypub (a new client-api.ts module +
  routes) or as a separate package? A separate package keeps
  @dwk/activitypub free of client-API-specific vocabulary/response shapes
  that have nothing to do with federation, matching the "confinement" spirit
  of the composition contract — but it would need to reach into
  @dwk/activitypub's DO the same way @dwk/mcp's tool contribution does.
• Auth model: reuse @dwk/indieauth/@dwk/oauth, or does the Mastodon app
  OAuth flow's specific quirks (dynamic client registration via
  /api/v1/apps predates RFC 7591 and isn't quite the same shape) need its
  own thin adapter over the shared primitives?
• How much of the Mastodon JSON response shape (Status, Account,
  Notification entities) is required for real clients to render correctly
  without erroring on missing fields — needs testing against at least one
  real client (Pixelfed's own, plus ideally a generic Mastodon client like
  Tusky) rather than guessing from the API docs alone.

Alternatives considered

• Status quo (MCP only): keeps scope small, but means "see your
  notifications" requires either a custom MCP-connected agent or reading the
  DO directly — not the experience a typical fediverse user expects.
• Push the read surface into @dwk/microsub (IndieWeb's own unified-inbox
  standard) instead of the Mastodon Client API: technically cleaner (stays
  inside IndieWeb standards, no foreign-platform API to maintain), but
  doesn't satisfy the actual ask here — a Microsub reader isn't "the Pixelfed
  client of your choice."

Additional context

• spec/fediverse-interop.md (non-goals section, "Platform client APIs")
• spec/packages/mcp.md (the current activitypub_list_inbox read path)
• conformance/pixelfed-qa.md — the manual run where this gap surfaced
• Tracking issue Fediverse platform interop: Lemmy, Pixelfed, and arbitrary platforms from the single actor (tracking) #273 (fediverse platform interop) — related but distinct:
  Fediverse platform interop: Lemmy, Pixelfed, and arbitrary platforms from the single actor (tracking) #273 is about S2S federation with other platforms; this is about C2S
  client access to this actor's own data.

[davidwkeith]

Status: all three phases are implemented and merged (#352, #357, #358; hardening in #364/#370), and #348/#349/#350 are closed. Keeping this open until the manual Pixelfed client run from conformance/mastodon-client-qa.md passes against the deployed conformance target (targets pixelfed-app/tusky are still pending in conformance/status.json).

[davidwkeith]

Closing: the close condition from the previous status comment is now met.

All three phases were already implemented and merged (#352/#357/#358, hardening #364/#370). The manual client run of conformance/mastodon-client-qa.md has now passed end-to-end against the deployed conformance target (2026-07-23, recorded in the runbook and status.json via #393):

• Pixelfed's own app: descoped as not-applicable — its login preflight fetches the proprietary /api/nodeinfo/2.0.json path and hard-requires software.name === "pixelfed" (≥ 0.12.3), refusing any non-Pixelfed server by design before OAuth starts, so it can never exercise this API surface (see the runbook's Scope for the full finding).
• Ice Cubes (iOS, substitute generic client): passing — login/consent/verify_credentials, home timeline with media/CW/alt text + own posts and interaction counters, and the pixelfed-qa step-4 like + reply as favourite/mention notifications. The run surfaced three quirks (missing accounts/:id/statuses, accounts/relationships swallowed by the dynamic route, missing createdAt), all fixed and fixture-tested in feat(mastodon-api,activitypub,conformance-target): serve own posts on profiles and fix ice cubes client-qa quirks #388.
• Tusky: still pending — it stays tracked by conformance/status.json and the release gate (which blocks any stable @dwk/mastodon-api release until it passes or is resolved), so it doesn't need this issue open.

The original ask — log in with an off-the-shelf Mastodon-API client and browse the actor's own feed and notifications — is demonstrated working with a real client against the deployed target.