Security, Capabilities, Nonces, and Permissions
Dashboard menu pages require manage_options. Most AJAX managers also check a nonce and manage_options. Public REST callbacks are deliberately open and validate request identity/signatures/security inside the handler.
WordPress capabilities decide who may open SmartSite admin screens; nonces protect state-changing browser requests against cross-site submission; callback validation protects public messages and webhooks. These mechanisms solve different problems and should appear together on sensitive handlers. The audit also records where a defense-in-depth capability check is missing so owners can address it in plugin code.
Work through this page by starting when you map each admin screen to manage_options. Finish by making sure you record unresolved gaps in the maintainer report before release; if that check fails, the field descriptions help identify whether the problem belongs to content, behavior, transport, or operations.
What this feature does and when to use it
Section titled “What this feature does and when to use it”Use this page during code review and before exposing new tools, routes, or administrative actions.
Use this feature in the following situations:
- You are reviewing a new or changed admin handler, REST route, webhook, or tool.
- You need negative tests for lower-privilege users, missing nonces, invalid tokens, or bad signatures.
- You are deciding whether a documented permission gap needs remediation before release.
Where to find it
Section titled “Where to find it”Before you begin
Section titled “Before you begin”- WordPress nonce/capability and REST security knowledge.
- The exact source used by the deployed plugin.
- A staging environment for negative tests.
Set it up step by step
Section titled “Set it up step by step”- Map each admin screen to manage_options.
- Map every state-changing admin_post/admin-ajax action to nonce and capability checks.
- Negative-test missing/invalid nonce and lower-privilege users.
- Review public token/chat/messages, active-channel, and webhook callback validation.
- Review secrets at rest and when rendered to administrator browsers.
- Review SSRF, email/header, option-data, and hook-tool boundaries.
- Record unresolved gaps in the maintainer report before release.
Fields, controls, and important values
Section titled “Fields, controls, and important values”Permissions determine who may configure the assistant or reach sensitive operations; they do not make generated text more accurate. Their importance is that instructions, tools, logs, and returned data can all be powerful or private. Capability, nonce, token, and signature checks must protect the correct boundary without blocking the public message flow the assistant needs.
| Field, control, or status | What SmartSite Assistant does with it | How to use it and why it matters |
|---|---|---|
| Admin pages | Registered with manage_options. | The manage_options capability restricts configuration screens to high-privilege WordPress accounts. That protects access to credentials, tools, logs, and behavior settings, although each state-changing handler still needs its own capability and request validation. |
| AJAX managers | Knowledge, tools, channels, analytics, translation, security, and wizard handlers check nonces/capabilities in audited code. | Changing “AJAX managers” can alter capability, wording, speed, cost, or language, but it cannot fill gaps in the knowledge base. Compare the same realistic prompts before deciding that a model or translation choice is an improvement. |
| Assistant admin_post handlers | Check action nonces but do not explicitly call current_user_can(manage_options); access normally begins on protected pages, but this is a defense-in-depth gap requiring owner review. | These handlers verify action nonces but do not explicitly repeat the manage_options capability check. Treat that as a defense-in-depth gap: a nonce protects request origin, not authorization, and the plugin owner should add and test the missing boundary. |
| Public chat routes | permission_callback __return_true; 32-hex token validation and security checks occur in callbacks. | Public permission callbacks let signed-out widgets reach chat, while token format, message validation, and security checks run inside the handler. Do not replace that design with login-only access unless the product audience changes; harden the callback instead. |
| WhatsApp POST | HMAC SHA-256 signature checked with App Secret. | Copy “WhatsApp POST” from the named provider without extra spaces, save it over HTTPS, and keep it out of captures and support messages. A masked value shows that WordPress stored something; the connection test shows whether the provider accepts it. |
| Design preview shell | admin_post render checks manage_options; sample REST routes return design-only data. | The rendered preview shell checks administrator capability, while its sample REST data is deliberately non-sensitive. Preserve that separation so preview convenience never exposes real conversations, credentials, tools, or provider responses. |
How to confirm it is working
Section titled “How to confirm it is working”Confirm Security, Capabilities, Nonces, and Permissions with the smallest representative end-to-end test. When the result differs from the success description, keep the exact input and state so troubleshooting can identify the responsible layer without changing unrelated AI settings.
Practical example
Section titled “Practical example”Add an explicit manage_options check to assistant create/edit/activate/delete handlers in a future plugin change, then update this report and tests.
Recommended practice
Section titled “Recommended practice”- Change one part of Security, Capabilities, Nonces, and Permissions at a time and keep a short record of the previous value and test result.
- Verify the saved result in the screen, visitor session, or connected service that actually consumes the setting.
Important warnings
Section titled “Important warnings”Common problems and focused checks
Section titled “Common problems and focused checks”| Problem | What to check and what to do next |
|---|---|
| Security, Capabilities, Nonces, and Permissions is missing or does not match this guide. | Confirm the plugin is active and the account can manage WordPress options. Trace the request through capability, nonce or public validation, storage, runtime consumption, and error handling. |
| A change on Security, Capabilities, Nonces, and Permissions does not produce the expected result. | Keep the exact notice and test case, then review the browser console and WordPress/PHP log. Trace the request through capability, nonce or public validation, storage, runtime consumption, and error handling. |
Screen reference
Section titled “Screen reference”- Capture
- Create a sanitized permission matrix diagram with Admin UI/AJAX/Public REST/Webhook rows and capability/nonce/signature columns.
- Show
- manage_options, nonces, public callback validation, HMAC, known gap
- Viewport
- Desktop, 1440 × 900
- Annotate
- Use numbered callouts only for controls referenced in the procedure.
- Redact
- OpenAI keys, tokens, secrets, personal information, private URLs, IP addresses, and conversation text