Skip to content

Architecture

Jump to bottom
Nick Hamze edited this page Sep 1, 2026 · 5 revisions

Architecture

The two roles

Fleet does not introduce a new WordPress site type.

  • The hub is the WordPress install where Fleet for OpenStation is activated alongside OpenStation.
  • A managed site is another WordPress install that has approved a connection from that hub. It needs OpenStation, but does not install Fleet.

The hub stores each manager's site list and encrypted tokens in that manager's user meta. The managed site stores an OpenStation OAuth grant tied to the WordPress user who approved it. Different hub managers have separate connections, and one managed site can authorize more than one hub.

OAuth discovery and connection

  1. The manager enters a public HTTPS site URL on the hub.
  2. Fleet requests the target's WordPress REST API index.
  3. OpenStation advertises authentication.openstation-fleet-oauth, including an RFC 8414 metadata URL.
  4. Fleet verifies that the issuer and authorization, token, and revocation endpoints share the target site's HTTPS origin.
  5. Fleet creates a random state value and PKCE verifier, encrypts the verifier temporarily, and sends its S256 challenge to the authorization screen.
  6. The target requires an administrator, explains site:manage as Full API access, and asks for approval.
  7. Approval returns a short-lived single-use code, the original state, and the target issuer to the hub's exact callback URI.
  8. Fleet verifies the state and issuer, then exchanges the code and original verifier for opaque access and refresh tokens.
  9. Fleet encrypts both tokens, requests the approving user's REST profile, and refreshes OpenStation status.

The first approval binds the hub's UUID client id to its exact callback URI. Later requests using that id must match it byte-for-byte.

Remote request flow

Fleet builds requests from the managed site's discovered REST root. It sends the short-lived access token as an HTTP Bearer credential. On the managed site, OpenStation authenticates the approving WordPress user, then the requested Core or plugin REST route runs its normal permission_callback.

Fleet refreshes an access token shortly before expiry. Refresh tokens rotate on every use, so the newly encrypted pair is persisted immediately before the request continues. One forced refresh and retry is allowed after a 401 response.

The focused Content, Plugins, and Settings tabs are convenience interfaces over Core routes. The API tab accepts GET, POST, PUT, PATCH, and DELETE for any route under the discovered REST root. This is the escape hatch for Core and plugin APIs that do not yet have a dedicated Fleet view.

Installing OpenStation

If the REST index does not advertise OpenStation OAuth, Fleet can use WordPress Core's Application Password authorization as a bootstrap connection.

  • Missing OpenStation: POST /wp/v2/plugins with the WordPress.org slug desktop-mode and active status.
  • Installed but inactive: POST /wp/v2/plugins/desktop-mode/desktop-mode with active status.
  • Already active: no installation request.

WordPress performs the download, filesystem checks, dependency handling, and activation. Fleet does not upload its own copy. Once OpenStation is active, disconnect the bootstrap credential and reconnect to use OAuth.

Disconnecting

For OAuth, Fleet posts the current refresh token to the discovered revocation endpoint and removes the local record only after success. The managed site can also revoke a grant under Users → Profile → Fleet connections.

For a bootstrap connection, Fleet deletes the exact Application Password UUID through Core before removing the local record. If the site is unreachable or refuses revocation, Fleet keeps the connection so the manager can retry.

WordPress and OpenStation building blocks

  • Core admin pages, forms, capabilities, and nonces
  • Core user meta and transients
  • Core safe HTTP functions and REST controllers
  • Core Plugins and Application Password APIs for bootstrap installation
  • OpenStation OAuth discovery and consent on managed sites
  • Authorization Code + PKCE, opaque bearer tokens, and rotating refresh tokens
  • WordPress's bundled sodium compatibility layer for encrypted hub storage
  • The OpenStation os.window.geometry filter for a centered, bounded Fleet window

Fleet registers a standard top-level wp-admin page. OpenStation already presents ordinary admin pages as desktop windows, so Fleet does not need a separate JavaScript application or private rendering framework.

Clone this wiki locally