# Waypoint Monitor

A small WordPress plugin that exposes a single authenticated REST endpoint reporting the site's WP core / PHP / plugin / theme state, the deployed git commit SHA, and the composer.lock hash. Used by the Waypoint package monitor to detect deploy drift without SSH or per-site app passwords.

## How it works

1. On activation the plugin generates a 64-char hex bearer token (`random_bytes(32)`), stores it in `wp_options`, and POSTs `{url, token, wp_version, plugin_version, admin_email}` to the package monitor's `/api/waypoint-monitor/register` endpoint.
2. The monitor round-trip-verifies the token by calling back to `/wp-json/waypoint-monitor/v1/status` before persisting it. (A forged registration without WP access can't poison the table.)
3. From then on the monitor fetches `/wp-json/waypoint-monitor/v1/status` with the stored token whenever it needs a drift snapshot.

## Endpoints

```
GET /wp-json/waypoint-monitor/v1/status
Authorization: Bearer <token>

{
  "plugin_version": "0.1.0",
  "wp_version": "6.9.4",
  "php_version": "8.3.30",
  "site_url": "https://example.com",
  "admin_email": "admin@example.com",
  "deployed_sha": "abc1234567890abcdef…",   // null if .git/HEAD isn't reachable
  "composer_lock_hash": "9f2e…",            // sha256, null if no composer.lock
  "plugins": [
    { "file": "akismet/akismet.php", "slug": "akismet", "name": "Akismet", "version": "5.4", "active": true }
  ],
  "themes": [
    { "stylesheet": "twentytwentyfour", "name": "Twenty Twenty-Four", "version": "1.4", "active": true }
  ],
  "checked_at": "2026-04-24T20:00:00+00:00"
}

GET /wp-json/waypoint-monitor/v1/ping     # cheap liveness probe, same auth
```

## Configuration

By default the plugin registers against `https://packagemonitor.apps.waypoint.agency`. Override via a constant in `wp-config.php`:

```php
define( 'WAYPOINT_MONITOR_API_URL', 'https://staging.packagemonitor.example.com' );
```

## Installation via Composer

Each tracked site's `composer.json` adds:

```json
{
  "repositories": [
    {
      "type": "vcs",
      "url": "git@github.com:statenweb/waypoint-monitor.git"
    }
  ],
  "require": {
    "statenweb/waypoint-monitor": "*"
  }
}
```

Then `composer update statenweb/waypoint-monitor` and the next deploy installs it under `wp-content/plugins/waypoint-monitor/`. WordPress activates it; on first activation it self-registers with the monitor.

## Security notes

- Token is constant-time compared (`hash_equals`) on every request.
- A daily cron heartbeat re-registers the site, so URL changes (domain swaps, staging clones) propagate to the monitor automatically.
- On failed first-time registration the plugin schedules a single-shot retry an hour out so transient network errors self-heal.
- Token rotation: deactivate + reactivate the plugin to issue a fresh token (the old one will fail to register against the monitor, which can prune it).
