Automattic/wordpress-activitypub / .agents/skills/review
review
VerifiedShared base for reviewing a diff, a branch or a PR in this plugin. How to read the diff, which repo guidelines to load for the changed paths, and the shape of a finding. Used by the code-review and security-audit agents.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.6 KB |
| guidelines/accessibility.md | markdown | 759 B |
| guidelines/authorization.md | markdown | 4.9 KB |
| guidelines/content-exposure.md | markdown | 6.9 KB |
| guidelines/cron.md | markdown | 897 B |
| guidelines/inbox.md | markdown | 7.6 KB |
| guidelines/integrations.md | markdown | 2.0 KB |
| guidelines/multisite.md | markdown | 1018 B |
| guidelines/output.md | markdown | 3.3 KB |
| guidelines/remote-fetch.md | markdown | 6.4 KB |
| guidelines/signatures.md | markdown | 4.5 KB |
| guidelines/supply-chain.md | markdown | 596 B |
| judge.md | markdown | 1.3 KB |
guidelines/inbox.md
View on GitHub# Inbox and handlers
Inbound activities: binding every reference to the signing actor, relayed activities, ownership checks.
Applies to: `includes/handler/**`, `includes/collection/**`, `includes/rest/class-inbox-controller.php`, `includes/rest/class-actors-inbox-controller.php`, `includes/functions-activity.php`, `includes/class-moderation.php`, `includes/class-comment.php`
## Past issues
- **Identity read from the file URL** (2026): incoming objects and actors were stored, looked up and compared through `object_to_uri()`, which returns the `url` of a media object. Create and Update looked for different keys and handed an activity back and forth, `is_same_host()` checked the host of the file instead of the object, and the signature checks bound the actor by its `url`. Everything that identifies now goes through `object_to_id()`.
- **Actor↔object binding gaps** (2026): Update, Undo and Accept handlers and remote upserts (`Remote_Actors`, `Remote_Posts`, `Interactions::update_comment`, `Inbox::undo`) changed or deleted records found by the sender's `object.id`, without checking the `actor` owns it. The Delete handler did check: `object_to_uri($activity['object']) === $activity['actor']`.
- **Relayed activity not re-authenticated** (2026): `Announce::handle_announce()` passed the inner activity to its handler as it came. The announcer is not necessarily its author, so an inner `Undo` or `Delete` could name another actor. The inner activity now has to be fetched from its own `id` with `host(id) === host(actor)`.
- **Ownership check fallbacks** (2026): the Update and Undo owner checks let records through when no owner was recorded, when the recorded owner was deleted or merged, or when the lookup and the check read different identifiers.
- **Alias matched on the actor's own claims** (2026): the Move handler accepted a target whose `alsoKnownAs` listed the origin's `url` or `webfinger`, values the origin declares about itself. Now only the origin's `id`, which the fetch confirmed, counts.
- **Content owner's block skipped** (2026): blocks were checked for the inbox's recipients only. A reply, reaction or quote reached a post or comment whose owner had blocked the sender whenever the owner was not a recipient.
- **Previously approved commenter matched on public values** (2026): core's "previously approved" rule matches name and email. The email of a Fediverse comment is its public handle, so a form comment, a reaction or another account behind the same handle got the approval of an earlier reply.
## Identity is the confirmed id
A decision that links two actors or trusts a remote author (an alias, a Move, auto-approval, an allow list) compares the `id` the fetch or the signature confirmed. Never `url`, `webfinger`, `preferredUsername`, a display name or a handle: an actor declares them about itself, anyone can type them into a form, and a server can give a handle to another account.
- Comment approval for Fediverse replies matches the earlier reply of the same actor (`Comment::check_previous_comment_approval()`; today through the remote actor post ID, see the `@todo`; the actor URI once actor posts are removed), and a comment from another source whose email matches a Fediverse commenter's handle is held. Such a rule can only hold a comment, never approve one that core would hold.
- It queries directly: `pre_get_comments` filters, this plugin's included, change `get_comments()` by context. A reply has the type `comment`, or `''` where core does not set that default (WordPress.com).
## Owner blocks
Read the "owner's block" pitfall in `AGENTS.md`. `Moderation::activity_is_blocked()` checks the owner of the content an activity targets, resolved with `get_target_post_id()`, before any handler runs.
- A block check inside one handler or in `Interactions` is a finding: every other handler and plugin bypasses it.
## Every reference is bound to the signing actor
The signature binds only the top-level `actor`. Everything else a handler reads, stores or acts on (`object`, `attributedTo`, any field specific to the activity) must be on the actor's host: `host(ref) === host(actor)`. This includes create paths: `Remote_Posts::add()` requires `actor === object.attributedTo`, like `Remote_Posts::update()`.
- Compare hosts with `is_same_host()`. It normalizes through `object_to_id()` and fails closed when a side has no host (handles and identifiers that are not `http(s)` parse to none). A hand-written `wp_parse_url` comparison that passes on an empty side fails open.
- Fold both sides of a host gate with `fold_host()`/`fold_authority()`, and make sure the folded host is the one the plugin connects to (see "Canonicalization" in `signatures.md`).
- A binding is worthless when one side is derived from the other, for example an `actor` filled in from the signing key. Pin whatever the handler still trusts on its own.
- The signature's `keyId` belongs to the `actor`, not only to its host: the key's owner (the stored actor the keyId resolves to, or the key as its host serves it through `Proxy::get()`) has to be the actor. On a server where users hold their own keys, a same-host check lets one user sign for another (see "Same-host key accepted for another actor" in `signatures.md`).
## Relayed and wrapped activities
Any path that takes an activity out of another one and dispatches it (today `Handler\Announce::handle_announce()` through `do_action( "activitypub_inbox_{$type}", $object, … )`) treats the inner activity as attacker-controlled, embedded or named by URL. An inner `Undo`/`Delete`/`Remove`/`Block` can name a victim.
- The inner activity is authentic only if it is fetched from its own `id` and `host( id ) === host( actor )`. `Http::get_remote_object()` does not check that the returned `id` matches the URL, so the caller does.
- That fetch uses `redirection => 0` and `$cached = false`. `Http::get()` follows redirects, and its cache is keyed by URL and read before the args apply, so an earlier cached redirect would undo `redirection => 0`. (Same as the CIMD fetch in `includes/oauth/class-client.php`.)
- `Inbox::undo()` and the Delete handler act on the inner activity's `actor`. If that actor can arrive unverified through a wrapper, it is critical.
- `handle_announce()`, and any new relay path, authenticates before dispatch.
## Ownership checks
- **A fallback is a gate of its own.** "No owner recorded, let it through" for old rows still binds the actor, at least `is_same_host( actor, <the identifier the record was found by> )`. Missing never means anyone.
- **A recorded reference that no longer resolves fails closed.** `if ( $owner instanceof WP_Post && … )` skips the check exactly when the owner is gone. Every path that deletes or merges a record an authorization depends on (actor Delete, Move, scheduled cleanup) repoints or removes the references in the same step.
- **Check the value you look up by.** Identify an object or an actor with `object_to_id()`, and use the same value for lookup, check and stored key, as `add_comment()` does. `object_to_uri()` returns the file (`url`) for `Image`, `Audio`, `Video` and `Document` and otherwise falls back to `url`; it is only for links (icons, avatars, attachments, `source_url`). A gate on one and a lookup on the other gets two different identifiers.
## Other inbox checks
Files: `includes/rest/class-inbox-controller.php`, `includes/rest/class-actors-inbox-controller.php`, `includes/handler/`.
- `type` is sanitized; it becomes part of a hook name (`do_action('activitypub_inbox_' . $type)`).
- `to`/`cc`/`bcc` do not cause SSRF through `get_local_recipients()`.
- `object` cannot inject stored content; the Create handler is checked for stored XSS.
- Remote content is sanitized before storage (`wp_kses_post()` or equivalent).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |