=== Opal Connect ===
Contributors: caseproofagent
Tags: site care, maintenance, application passwords, health check
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect your site to Opal Care with its own narrow user. No password is typed anywhere, and Opal never gets an administrator login.

== Description ==

Opal Connect links this site to [Opal Care](https://opalagent.app/), so Opal can run its checks and prepare drafts for you to approve.

WordPress can already hand an app an Application Password, but that password belongs to whoever is signed in, usually an administrator. Opal Connect gives Opal **its own user**, `opal`, with a narrow role, `opal_care`, instead.

**Opal can always:** read the site, run its health checks, write drafts of posts and pages for you to approve, and upload media.

**Optional, you choose when you connect:** publish what you approve; apply plugin and theme updates you approve.

**Opal can never:** change settings; install, activate, edit or delete plugins or themes; update WordPress itself; create, edit, promote or delete users; delete anything (the one exception: Opal can revoke its own Application Password, so it can disconnect itself); export or import site data; post unfiltered HTML; or do anything network-wide. These are denied even if another plugin grants them.

What the plugin does on your site:

* adds one page, Settings > Opal;
* when you click Connect and finish, creates the `opal_care` role and the `opal` user with an Application Password;
* when you click Disconnect (or deactivate the plugin), revokes that password and removes the user and the role. Anything the `opal` user wrote is reassigned to you.

What it never does: add anything to the public site, load remote scripts or styles, track you, run scheduled tasks, edit files, or contact any server before you click Connect. It never stores Opal's password: WordPress keeps only a hash, and the plugin keeps only the date, the user ID, the capabilities and the Application Password's ID.

The `opal` user cannot sign in with a password, and cannot reset one. It works only through its Application Password.

= About the user this plugin creates =

Opal Connect creates one WordPress user, `opal`, with one role, `opal_care`. It is never created on activation: only when an administrator clicks Connect, confirms on myopal.dev, and then clicks Finish connecting on Settings > Opal. That page says before you click that it will create the `opal` user and send its Application Password to Opal.

* It is not an administrator. The `opal_care` role has only the capabilities listed above, and the plugin denies the rest even if another plugin grants them.
* It is not hidden. It is listed under Users like any other user, its profile says "Opal Care. Created by the Opal Connect plugin", and Settings > Opal shows that it exists and what it may do.
* It exists so that Opal never uses your own login: WordPress's built-in Application Passwords belong to the user who creates them, usually an administrator.
* It is removed, with its role and its Application Password, when you click Disconnect, deactivate the plugin, or delete the plugin. Anything it wrote is reassigned to you.
* If a user named `opal` already exists and this plugin did not create it, the plugin refuses to connect and never touches that user.

== External services ==

This plugin connects to **Opal (myopal.dev)**, the Opal Care service run by the plugin's authors. It is needed to link this site to your Opal Care account. Nothing is sent until you click Connect, and the plugin contacts no other service.

* **When you click Connect**, your browser (not this site) goes to myopal.dev/connect/wordpress/start with your site's address, the address of this settings page to come back to, a one-time challenge, and the optional permissions currently granted.
* **When you click Finish connecting** after coming back, this site sends one HTTPS request to myopal.dev/connect/wordpress/finish with: Opal's one-time code, the one-time verifier for the challenge, your site's address, the user name `opal`, the new Application Password and its ID, and the list of capabilities granted. If you later change the optional permissions, the same request is sent without any password.
* **When you click Disconnect, or deactivate the plugin**, this site sends one HTTPS request to myopal.dev/connect/wordpress/disconnect with your site's address and the Application Password's ID, so Opal deletes its stored copy.

Opal's [terms of service](https://opalagent.app/terms/) and [privacy policy](https://opalagent.app/privacy/).

== Installation ==

1. Install and activate Opal Connect from Plugins > Add New, or upload the `opal-connect` folder to `/wp-content/plugins/`.
2. Go to Settings > Opal and click Connect.
3. Sign in on myopal.dev, confirm this site and choose the optional permissions.
4. Back on Settings > Opal, click Finish connecting.

Your site must use HTTPS and have Application Passwords turned on (the WordPress default on HTTPS sites).

== Frequently Asked Questions ==

= Does Opal get my administrator password? =

No. Opal gets its own user, `opal`, and an Application Password for that user only. You never type a password.

= Why does the plugin create a user? =

So that Opal acts as itself, with a narrow role, and never as you. An Application Password always belongs to one user; without a separate user, Opal would hold an administrator's. The user is created only when you click Finish connecting, and removed when you disconnect. See "About the user this plugin creates" above.

= What can Opal do on my site? =

Read the site, run health checks, write drafts and upload media. Publishing and applying updates are optional and only if you tick them. Settings, plugins, themes, users, deleting, and exporting are always denied.

= How do I disconnect? =

Click Disconnect on Settings > Opal, or deactivate the plugin. You can also revoke the Application Password under Users > opal; then click Disconnect to finish cleaning up.

= Does it work on multisite? =

Not yet. On a multisite network the Connect button explains this and does nothing.

= Can I point it at a test copy of Opal? =

Developers can define `OPAL_CONNECT_SERVICE_URL` in wp-config.php as another https address. Without it, the plugin uses https://myopal.dev.

== Screenshots ==

1. Settings > Opal before connecting: what Opal can always do, the optional permissions, what it can never do, and the Connect button.
2. Back from myopal.dev: choose the optional permissions, then click Finish connecting to create the `opal` user.
3. Settings > Opal when connected: since when, as which user, what Opal may do, and Disconnect.

== Changelog ==

= 0.2.0 =
* A read-only route, opal-connect/v1/updates, that tells Opal which plugins and themes have an update waiting, so her care checks can report them. It needs no extra permission and changes nothing.

= 0.1.0 =
* First release: Connect, Disconnect, the opal_care role and the hard capability denial.

== Upgrade Notice ==

= 0.1.0 =
First release.
