|
| 1 | +# Access Controls |
| 2 | + |
| 3 | +## Summary |
| 4 | + |
| 5 | +Access Controls let administrators limit each supported AI feature to chosen roles and specific users. A restriction applies wherever the feature's abilities run, not just in the plugin's own screens. Nothing changes for anyone until an administrator turns access control on for a feature **and saves**. |
| 6 | + |
| 7 | +## Overview |
| 8 | + |
| 9 | +### For End Users |
| 10 | + |
| 11 | +On the AI settings page (**Settings → AI**), open the **Developer Tools** menu (the wrench icon) and select **Access controls**. Each enabled feature that supports access control then shows: |
| 12 | + |
| 13 | +- **Enable access control**: turns the restriction on or off for that feature. |
| 14 | +- **Roles**: one checkbox per role that has the `edit_posts` capability. **Administrator** and **Editor** are checked by default. |
| 15 | +- **Users**: search for and add individual users. Listed users can always use the feature, whatever their role. |
| 16 | +- **Save**: appears once you change something. Nothing is stored until you click it. |
| 17 | + |
| 18 | +When the **Access controls** view is turned off, a feature that is actually restricted shows "Access restricted to selected roles and users." so the restriction stays visible. Turning the view off never clears saved settings. |
| 19 | + |
| 20 | +### What changes, and when |
| 21 | + |
| 22 | +- **Access control off** (the default): access is identical to before. Anyone who passes the feature's normal permission checks can use it. |
| 23 | +- **Turned on but not saved**: nothing is written, so access is still identical to before. |
| 24 | +- **Turned on and saved**: only the checked roles and the listed users can use the feature. If you save without touching the defaults, Administrator and Editor are saved. That can be stricter than before. For example, Authors and Contributors lose access. |
| 25 | +- **No roles checked and no users listed**: nobody can use the feature, including administrators. |
| 26 | + |
| 27 | +On multisite, super admins can always use every feature. |
| 28 | + |
| 29 | +Access control only ever adds a restriction. Each ability's own permission checks still apply, so adding a user here does not let them edit posts they otherwise could not. |
| 30 | + |
| 31 | +### Where the restriction applies |
| 32 | + |
| 33 | +The restriction applies to the feature's abilities on every path they run: |
| 34 | + |
| 35 | +- the plugin's own buttons and screens in wp-admin and the editor (users without access do not get the feature's UI); |
| 36 | +- the Abilities REST API (`/wp-abilities/v1/abilities/{name}/run`); |
| 37 | +- MCP over HTTP; |
| 38 | +- `runAbility()` in JavaScript, and server-side calls to `wp_get_ability()->execute()`; |
| 39 | +- abilities one feature calls from another. For example, alt text generated during Image Generation is checked against the Alt Text Generation feature's settings; |
| 40 | +- Text to Speech's own REST routes (`/ai/v1/text-to-speech/{id}`), which are not abilities but check the same capability. |
| 41 | + |
| 42 | +A user without access gets a `wpai_feature_access_denied` error (HTTP 401 when logged out, 403 when logged in). |
| 43 | + |
| 44 | +**Automatic runs are not affected.** Work the feature does on its own, without a user asking, carries on whatever the access settings say. For example, Comment Moderation still analyses new comments, and Text to Speech jobs that are already queued still finish. |
| 45 | + |
| 46 | +**WP-CLI without `--user` is not restricted.** Commands run through WP-CLI without `--user` bypass access control. With an explicit `--user`, the restriction applies to that user, so `wp mcp-adapter serve --user=bob` respects Bob's access. This includes MCP over STDIO, which runs through WP-CLI. |
| 47 | + |
| 48 | +### Which features support it |
| 49 | + |
| 50 | +Only features whose `access_control` metadata is `true` show these controls. Access control is opt-in. Every built-in feature outside the **Admin** category opts in, and so do Comment Moderation and Suggest Reply. Other admin features already require `manage_options`. Third-party features must set `'access_control' => true` to opt in. |
| 51 | + |
| 52 | +### Settings export and import |
| 53 | + |
| 54 | +Access control settings are **not** included in [settings export and import](settings-import-export.md). Role slugs and user IDs differ between sites, so configure access controls on each site directly. |
| 55 | + |
| 56 | +## Stored options |
| 57 | + |
| 58 | +Each supported feature stores three options, registered in their own option group (`ai_experiments_access`) and exposed through the core `/wp/v2/settings` endpoint: |
| 59 | + |
| 60 | +| Option | Type | Default | |
| 61 | +|---|---|---| |
| 62 | +| `wpai_feature_<id>_access_control_enabled` | boolean | `false` | |
| 63 | +| `wpai_feature_<id>_roles` | list of role slugs | unset, meaning no role restriction | |
| 64 | +| `wpai_feature_<id>_users` | list of user IDs | `[]` | |
| 65 | + |
| 66 | +An unset roles option is different from an empty list. Unset means "no restriction yet". A saved empty list means "no role has access". |
| 67 | + |
| 68 | +## For Developers |
| 69 | + |
| 70 | +### The `wpai_use_feature` capability |
| 71 | + |
| 72 | +Access is decided by the `wpai_use_feature` meta capability, with the feature ID as its argument: |
| 73 | + |
| 74 | +```php |
| 75 | +if ( current_user_can( 'wpai_use_feature', 'title-generation' ) ) { |
| 76 | + // The current user may use Title Generation. |
| 77 | +} |
| 78 | +``` |
| 79 | + |
| 80 | +The plugin maps it to `exist` (allowed) or `do_not_allow` (denied) in a `map_meta_cap` filter at priority 10. The recommended way to extend the check is your own `map_meta_cap` filter at a later priority that adds a requirement to the plugin's result. The following example also requires `publish_posts` for Title Generation. The admin's role and user settings stay in force, so a user must pass both: |
| 81 | + |
| 82 | +```php |
| 83 | +add_filter( |
| 84 | + 'map_meta_cap', |
| 85 | + static function ( array $caps, string $cap, int $user_id, array $args ): array { |
| 86 | + if ( 'wpai_use_feature' === $cap && 'title-generation' === ( $args[0] ?? '' ) ) { |
| 87 | + // Also require publish_posts, on top of the access control settings. |
| 88 | + $caps[] = 'publish_posts'; |
| 89 | + } |
| 90 | + return $caps; |
| 91 | + }, |
| 92 | + 20, |
| 93 | + 4 |
| 94 | +); |
| 95 | +``` |
| 96 | + |
| 97 | +Run your filter after priority 10 so it sees the plugin's result. Append to `$caps` rather than replacing it: returning a new array discards the plugin's decision. |
| 98 | + |
| 99 | +The `user_has_cap` filter also works, but it only sees the primitive `exist` or `do_not_allow` result, not the roles and users behind it. Core never grants `do_not_allow`, so `user_has_cap` is mainly useful for denying access. |
| 100 | + |
| 101 | +### Linking abilities to features |
| 102 | + |
| 103 | +Features register their abilities with `Abstract_Feature::register_feature_ability()`. It adds the feature ID to the ability's `wpai_feature` meta key and then calls `wp_register_ability()`. The plugin checks `wpai_use_feature` for that feature whenever an ability with this meta key runs. |
| 104 | + |
| 105 | +Abilities registered directly with `wp_register_ability()` are not tied to any feature, so only their own `permission_callback` applies. `register_feature_ability()` adds the meta key only for features that opt in with `'access_control' => true`. |
| 106 | + |
| 107 | +On WordPress 7.0.x, the check applies only to abilities whose class extends `Abstract_Ability`, because the core `wp_ability_permission_result` filter arrives in WordPress 7.1. |
| 108 | + |
| 109 | +Feature UI that should be hidden from users without access belongs in `register_ui()`. See the [Developer Guide](../DEVELOPER_GUIDE.md). |
0 commit comments