# WordPress Bridge Core Update Standard v1

## Purpose

WP Flask Bridge is the permanent trust core installed on each customer site.
It can receive small signed releases as the platform evolves; customers do not
need to wait for a final monolithic version or reinstall the plugin manually.

Core releases are independent from App Pack releases. They use a separate
catalog, database record, signing key, pinned public key, JWT scopes, and
download endpoint. Compromise of an App Pack signing key therefore does not
authorize a Core update.

## Release contract

Every release contains `bridge-release.json` and one deterministic ZIP rooted
at `wp-flask-bridge/`. The signed metadata includes:

- immutable version and release channel;
- plugin entrypoint and matching WordPress `Version` header;
- minimum WordPress and PHP versions;
- schema version, security flag, and customer-safe release notes;
- artifact name, byte size, SHA-256 digest, and detached Ed25519 signature.

Supported channels are `development`, `beta`, `stable`, and `security`. A site
only receives releases from its configured channel. The first development
baseline is `0.3.0-dev`; `0.3.1-dev` is the first detectable self-update.

## Customer lifecycle

1. Core refreshes its authenticated catalog twice daily and from the Apps UI.
2. A higher compatible version produces a WordPress administrator notice.
3. The Apps screen shows installed/available versions and release notes.
4. The administrator selects **Install signed Core update**.
5. Core requests fresh metadata and downloads with a short-lived site JWT.
6. Before extraction, it verifies byte size, SHA-256, the independently pinned
   Ed25519 signature, ZIP root, paths, links, limits, manifest, and entrypoint.
7. WordPress negotiates `WP_Filesystem` (Direct, FTP, FTPS, or SSH). Core never
   stores or returns filesystem credentials.
8. WordPress's native plugin update hooks preserve activation and create a
   temporary backup. Failed replacement schedules automatic restoration.

Plugin files are replaced; customer configuration remains in WordPress options
and is not bundled in the ZIP. Future data migrations must be versioned,
idempotent, safe to rerun after a failure, and executed after file replacement.

Core catalog and security-update access is not restricted by paid App
entitlements. A customer must remain able to repair the trust core even when a
subscription is expired or no optional apps are enabled. Runtime app calls
remain independently protected by subscription and capability checks.

## Operator workflow

Keep the private key outside every source repository. Initialize it once:

```text
venv/bin/python scripts/init_bridge_signing_key.py
```

Build a deterministic signed release and register its verified artifact:

```text
venv/bin/python scripts/build_wordpress_bridge.py \
  --source ../absolutems/wp-content/plugins/wp-flask-bridge \
  --output /var/www/html/.platform-artifacts/wordpress-bridge

venv/bin/python scripts/register_wordpress_bridge_release.py \
  /var/www/html/.platform-artifacts/wordpress-bridge/<artifact>.zip \
  /var/www/html/.platform-artifacts/wordpress-bridge/<release>.json
```

Registration recomputes size and SHA-256 and verifies the signature with the
external Core public key. Publishing a version twice with different bytes is
forbidden; issue a new version instead.

Revoke a bad release with a customer-safe explanation:

```text
venv/bin/python scripts/revoke_wordpress_bridge_release.py \
  <version> --reason "<reason>"
```

Revoked releases retain audit metadata but have no download URL and cannot be
installed. Emergency key rotation and a formally tested manual disaster
recovery procedure remain production-hardening requirements before stable
general availability.

## Acceptance test

For each release channel:

1. Leave the site running the signed baseline.
2. Publish a higher signed version without modifying the installed directory.
3. Refresh the catalog and confirm the notice and Apps action.
4. Validate the ZIP through the exact Core verifier.
5. Install through the browser and confirm the plugin remains active, its
   version changes, settings remain present, and diagnostics load.
6. Repeat on representative Direct and remote-filesystem staging sites.

The AbsoluteMS baseline currently passes steps 1–4 for `0.3.0-dev` to
`0.3.1-dev`. Browser installation is intentionally left for the administrator
so the end-to-end test uses the same path as a customer site.