ADR-0007: WordPress roles are declared in the app, not created over REST
ADR-0007: WordPress roles are declared in the app, not created over REST
Section titled “ADR-0007: WordPress roles are declared in the app, not created over REST”Status: Accepted · Date: 2026-10-18
Context
Section titled “Context”WordPress roles are created with add_role() and capabilities are attached
with add_cap(). Both are PHP APIs. The REST API has no roles endpoint and no
capabilities endpoint — the users endpoint
only reads roles, capabilities and extra_capabilities, and only with
context=edit and an authenticated caller holding list_users.
That leaves three audiences with three different needs:
- The site, which must end up with the role and its capabilities. Only
PHP can do that: a plugin, an mu-plugin, or
wp-cli role add. - The dashboard, which owns the user experience and must decide what to show, which routes to guard, and what the policy is.
- The person deploying, who needs to know whether the site actually matches the declaration instead of assuming it does.
A fourth problem makes naive adoption worse: wp_update_user() silently drops
a role slug the site does not know. The response is a 200 with the user
unchanged, so useWpUpdateUser({ roles }) reports success for a grant that never
happened. An audit that accepts “no error” as proof inherits that lie.
Decision
Section titled “Decision”The WordPress adapter separates declaring the model from applying it, and never pretends the second is possible from JavaScript.
A role declaration (WpRoleDefinition) carries both capability vocabularies:
capabilities— the toolkit’s namespaced capabilities (orders:read:own), which driveuseCan()and the framework guards.wpCapabilities— WordPress’ snake_case names (read_private_orders), the declaration the site must hold.
They are never derived from one another. orders:read:own is a policy
statement; read_private_orders is a WordPress permission. Collapsing them
would hide who may touch somebody else’s record.
On top of the declaration:
useWpSyncRoles()publishes declarations to the access service so guards understand WordPress role slugs. It is explicit, not a side effect of declaring:useCan()throws on an unknown slug by design, and that throw is the signal that the boot sequence is incomplete.useWpAssignRole()verifies the roles on the response and fails with422when the grant did not land, naming the missing role. Unassignment is idempotent instead, because nothing there can be silently ignored.useWpAuditRole()compares the declaration against the capabilities WordPress reports for the role’s holders.grantedis the intersection across holders — a capability only one holder has is not a capability the role grants. With no holders the status isunverifiable, neververified: an empty list is not proof.
Consequences
Section titled “Consequences”Better. A no-PHP dashboard gets a real authorization model instead of a role slug string, and gets told — with evidence — when the site disagrees with it. A silently dropped grant can no longer masquerade as a success. Roles, capabilities and guards read one vocabulary, so a route guard and the button that hides itself cannot drift apart.
Worse. The deployment still needs a PHP step somewhere (a plugin, an
mu-plugin, wp-cli) for a role that does not exist yet; the adapter cannot
remove that step, only stop pretending it is unnecessary. An audit needs
context=edit, so a subscriber-level token cannot run one. Every role call asks
for context=edit and pays the larger payload. And wpCapabilities is
declaration-only data: it is never enforced by this toolkit, only compared, so
a stale declaration is possible where an enforced one would not be.
- WordPress guide — roles and capabilities without PHP
- Access Control — the registry the declarations feed.