# Waypoint Agent

WordPress plugin that connects a site to the Waypoint platform — reporting site state to the monitor and providing authenticated REST endpoints for content ingestion, draft publishing, and media management.

## Requirements

- WordPress 6.0+
- PHP 8.0+

## Installation

Install via the dist repo (Composer). The source repo requires private credentials for ACF Pro; the dist repo ships with dependencies pre-built.

```json
{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/statenweb/site-agent-dist"
    }
  ],
  "require": {
    "statenweb/site-agent": "*"
  }
}
```

## WP-CLI Commands

```bash
# Rotate the HMAC agent key (writes new key to .env)
wp waypoint-agent rotate-key
wp waypoint-agent rotate-key --show   # also prints the new key

# Flush all caches (object cache + WP Rocket + EWWW + SpinupWP)
wp cache flush   # Waypoint's Flush Everything runs automatically after this

# Grant Waypoint Super Admin role to a user
wp waypoint-agent waypoint-admin <user_id>
```

## Settings Page

**Tools → Waypoint Agent** — visible only to users with the `waypoint_super_admin` role.

| Setting | Default | Description |
|---|---|---|
| Waypoint Dashboard Widget | On | Branded status widget on the admin dashboard |
| Disable Comments Sitewide | On | Removes comment support, closes REST endpoint, hides UI |
| Remove Default WordPress Content | On | Deletes "Hello world!" post on first run |
| RankMath Tweaks | On | Suppresses `slack_enhanced_data` from OpenGraph output |
| RankMath: Homepage OG Image Fallback | On | Uses Default Social Share Image on homepage when no explicit image is set |
| RankMath: Disable Content AI | On | Disables the RankMath Content AI module |

## Roles & Capabilities

**`waypoint_super_admin`** — granted the `set_waypoint_helper_settings` capability, which is required to view or change the plugin settings page. The role is auto-assigned to the first registered user. On plugin activation, the oldest administrator is seeded as super admin if none exists. Additional super admins can be granted via WP-CLI.

Only a Waypoint Super Admin can grant the role to other users (`wp waypoint-agent waypoint-admin <user_id>`).

## Authentication

REST endpoints under `/waypoint-agent/v1/*` authenticate via **HMAC-SHA256** — requests must include `X-Waypoint-Timestamp` and `X-Waypoint-Signature` headers. The signing key is stored in `.env` as `WAYPOINT_AGENT_KEY`.

Monitor endpoints under `/waypoint-monitor/v1/*` use a **Bearer token** stored in `wp_options`.

## Environment Variables

| Variable | Description |
|---|---|
| `WAYPOINT_AGENT_KEY` | HMAC-SHA256 signing key for agent REST endpoints. Generate with `wp waypoint-agent rotate-key`. |
| `WAYPOINT_MONITOR_API_URL` | Override the monitor registration URL (optional). |

## Integrations

- **WP Rocket** — page cache, minified CSS/JS, critical CSS, LCP/ATF detection data
- **EWWW Image Optimizer / Easy IO** — ExactDN cache flush
- **SpinupWP** — server-level page cache purge
- **RankMath** — OpenGraph tweaks, Content AI disable
- **ACF Pro** — loader included

## Monitor Endpoints

```
GET /wp-json/waypoint-monitor/v1/status    # site state snapshot (auth: Bearer token)
GET /wp-json/waypoint-monitor/v1/ping      # liveness probe
POST /wp-json/waypoint-monitor/v1/rotate-key
```

## Security

- Bearer token is constant-time compared (`hash_equals`) on every request.
- HMAC signatures include a timestamp to prevent replay attacks.
- A daily cron heartbeat re-registers the site so URL/domain changes propagate automatically.
- On failed first-time registration, a single-shot retry is scheduled an hour out.
