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/authorization.md
View on GitHub# Authorization
Who may call a route or change a setting: ownership, capabilities, user ID 0, OAuth scopes.
Applies to: `includes/rest/**`, `includes/oauth/**`, `includes/wp-admin/**`
## Past issues
- **Ownership checks written by hand** (2026): endpoints decided ownership themselves instead of using `verify_owner()` / `maybe_verify_owner()` (`includes/rest/trait-verification.php`). The Outbox controller treated `current_user_can('activitypub')` as owning every user's outbox, and the SSE outbox stream checked the owner but queried by the actor type meta (`_activitypub_activity_actor` = `'user'`), so it sent every user's items.
- **User ID 0** (2026): `Actors::BLOG_USER_ID` is `0`, and so is `get_current_user_id()` when logged out. `user_can_activitypub( get_current_user_id() )` or `get_current_user_id() === $user_id` without a login check let anonymous callers act as the blog actor.
- **OAuth scope missing next to identity** (2026): a bearer token proves who the caller is, not what it may do. Read paths that only checked the user served data to tokens without the `read` scope.
- **Uncounted discovery trigger** (2026): the consent form on `wp-login.php` fetched the Client ID Metadata Document of unknown clients, outside the REST routes that count callers. Now discovery runs only during a REST request.
- **Internal rows editable by users** (2026): the outbox, inbox, OAuth client and tombstone post types only blocked `create_posts` or set no capabilities, so `edit_post` mapped to the default post rights. Authors could rewrite their own outbox rows over XML-RPC, and a local delivery, which skips the signature, trusted the row as stored.
## Ownership
- Access to a route and the scope of its query are two checks. Verify both.
- Use `verify_owner()` instead of a hand-written owner check.
- Any check keyed on a user ID that can be `0` confirms `is_user_logged_in()` first. This only matters where the result grants access or exposes data. A redirect choice on a `__return_true` endpoint whose branches all gate themselves (for example by sending to `wp-login`) is not a finding.
- For every stored reference an authorization reads (owner IDs in comment or post meta, stored actors), find the paths that delete or merge the referenced record. Each one repoints or removes the references, or the check fails closed when they dangle (see "Ownership checks" in `inbox.md`).
## OAuth
Files: `includes/oauth/`, `includes/rest/oauth/`.
- `is_user_logged_in()`, `get_current_user_id()`, `current_user_can()` and `verify_owner()` say who the caller is. Every owner-only read also requires `read` and every change `write`, whatever the transport: a stream or a POST that only reads is a read. Use `verify_authentication()`, `owner_may_read()` or `OAuth_Server::permits_scope()`.
- The same data has several read paths: paged collection, event stream, single item, embedded or seek responses, and callers outside REST that authenticate a bearer themselves. List them per collection; each applies the same scope. Shared code that branches per collection or type applies it in every branch.
- Tests cover a token without the needed scope on every path and branch, not only the reported one.
- PKCE: `plain` is blocked, not just discouraged.
- Dynamic client registration is rate-limited.
- `redirect_uri` validation handles custom schemes safely.
- Tokens are stored hashed, expire, and users cannot revoke other users' tokens.
- The consent screen has CSRF protection.
- The Client ID Metadata Document fetch is checked for SSRF (see `remote-fetch.md`).
- Client discovery runs only where the caller was counted: `Client::is_discoverable_url()` requires a REST request. A new screen or route that resolves a `client_id` shows known clients only, or counts its callers first.
## Admin and capabilities
Files: `includes/wp-admin/`, `includes/rest/`.
- Admin pages check `manage_options` or the fitting capability.
- Per-user settings (like the profile ActivityPub toggle) check that it is the right user.
- Every form submission has a nonce check. Each `phpcs:ignore WordPress.Security.NonceVerification` explains why it is safe.
- A post type only the plugin writes uses `Post_Types::LOCKED_CAPABILITIES` with `map_meta_cap`, so nobody can create, edit, publish or delete its posts through XML-RPC, REST or the admin. A new `ap_*` post type is locked or listed as editable with its reason in `test_internal_post_types_are_locked()`. `ap_post` and `ap_actor` are still editable, because the admin app reads them with `context=edit`.
- Content that is delivered without a signature (a local inbox) is checked against an identity recorded when the row was written, not against what the row says now.
- A gate fed by `rawurldecode()`/`urldecode()` sees a value REST has usually decoded once already. Check what the second decode lets in: `*`, `_`, the empty string, characters a later sanitizer strips, encoded spellings of a stored identifier (see "Canonicalization" in `signatures.md`).
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 |