Automattic/wordpress-atmosphere / .agents/skills/review
review
UnverifiedShared 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 | 7.1 KB |
| guidelines/accessibility.md | markdown | 781 B |
| guidelines/authorization.md | markdown | 2.8 KB |
| guidelines/content-exposure.md | markdown | 6.8 KB |
| guidelines/cron.md | markdown | 1.9 KB |
| guidelines/hooks.md | markdown | 2.3 KB |
| guidelines/oauth.md | markdown | 3.6 KB |
| guidelines/output.md | markdown | 610 B |
| guidelines/records.md | markdown | 2.1 KB |
| guidelines/remote-fetch.md | markdown | 5.3 KB |
| guidelines/supply-chain.md | markdown | 582 B |
| guidelines/uninstall.md | markdown | 2.0 KB |
| guidelines/well-known.md | markdown | 1.4 KB |
| judge.md | markdown | 1.2 KB |
guidelines/oauth.md
View on GitHub# OAuth, DPoP and tokens
The native OAuth flow (PKCE, PAR, DPoP) and the credentials it leaves behind.
Applies to: `includes/oauth/**`, `includes/class-api.php`, `includes/rest/class-client-metadata-controller.php`, `includes/rest/class-legacy-client-metadata-controller.php`, `includes/rest/admin/class-connection-controller.php`
## Flow
- PKCE: `S256` is required, `plain` is blocked.
- PAR: the `request_uri` is validated.
- `redirect_uri` validation cannot be steered to leak tokens.
- The authorization server discovery chain (handle → DID → PDS → auth server) cannot be poisoned (see `remote-fetch.md`).
- The client metadata endpoint exposes nothing sensitive.
- Refresh invalidates the old tokens.
- Refresh errors tell transient failures (network, 5xx) apart from permanent ones (revoked, `invalid_grant`).
- Distinct failure modes get distinct error codes. One `WP_Error` code reused across "transient missing", "legacy session shape" and "decrypt OK but plaintext malformed" leaves support unable to triage and users without the right remediation.
## DPoP proofs
Files: `includes/oauth/class-dpop.php`
- ES256 keys are generated on the P-256 curve with proper entropy.
- Private keys never reach logs, error messages or HTTP responses. The public JWK in the proof header never carries the private `d` parameter.
- The `ath` claim binds the proof to the access token, and the proof's `jwk` header matches the key bound to that token. Accepting a different, caller-supplied `jwk` next to a valid `ath` is a confused deputy.
- `htu` and `htm` match the request.
- `jti` has enough entropy to prevent replay.
- Server-provided nonces are stored and replayed correctly.
- With native OpenSSL signing: DER-to-raw signature conversion handles leading zeros and variable-length integers, and JWK-to-PEM conversion produces valid SEC1/PKCS#8 structures.
Freshness, for proofs and for any signed nonce or timestamp coming back from the auth server or PDS:
- `iat` is required, and its window is a few minutes either side of the server clock, not hours. A wide window lets an intercepted proof be replayed.
- Where the spec allows `exp` or `nbf`, the future expiry is capped at a small bound (for example 5 minutes), so nobody can mint a long-lived proof.
## Tokens, keys and secrets
Files: `includes/oauth/class-encryption.php`, `includes/oauth/class-client.php`, `includes/oauth/class-nonce-storage.php`, `includes/class-api.php`
- Encryption uses libsodium with proper key derivation.
- Tokens are never logged, put in error messages or stored in plaintext. PDS error responses do not pass token values to the browser.
- DPoP private keys (ES256) are stored encrypted and cannot be extracted through the admin UI.
- The connection data in `wp_options` is encrypted and not readable by lower-privilege users.
- Token scope is checked before PDS requests.
- Nonce storage (`class-nonce-storage.php`) cannot be written by unauthenticated users.
- Every crypto output is computed into locals first; state is written only after every encrypt succeeded. `Encryption::encrypt()` can throw (`random_bytes`, `sodium_crypto_secretbox`); inlined into the third `set_transient()` argument, a throw leaves the first two transients orphaned for the full TTL.
## Revocation
Files: `includes/oauth/class-client.php` (`disconnect()`), `uninstall.php`
- Disconnect revokes the refresh token at the auth server (`POST /oauth/revoke`). A local-only delete leaves a refresh token that stays valid wherever it leaked to.
- Uninstall cleans up local state and remote tokens, so a credential leaked from a deleted install does not stay valid forever (see `uninstall.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: 472k | 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: 472k | 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: 472k | 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 |