PhantomWP Connect Plugin

PhantomWP Connect is the WordPress plugin that turns your WordPress site into a fully wired backend for your PhantomWP-generated Astro frontend. It is the trusted communication layer between PhantomWP and your WordPress install.

You do not strictly need this WordPress plugin to use PhantomWP. Read-only access over the public REST API works for simple content sites. The plugin is what unlocks writes, agentic AI scaffolding, visitor authentication, and signed two-way communication.

What the Plugin Does

In a single install, PhantomWP Connect gives you:

• Self-pairing with your PhantomWP project on first admin visit (no API key copy-paste)
• Signed two-way communication between PhantomWP and WordPress (ECDSA P-256 + SHA-256)
• JWT visitor authentication for login, registration, and account flows on your Astro site
• Agentic AI write access so the PhantomWP AI assistant can create posts, pages, custom post types, taxonomies, and field groups directly in your WordPress
• Encrypted at-rest storage (AES-256-GCM) for API keys and JWT secrets
• WooCommerce integration for customer login, registration, and account features

Installing the WordPress Plugin

Option A: From the PhantomWP IDE (recommended)

1. Open your project in the PhantomWP IDE
2. Click the WordPress icon in the header bar
3. Enter your WordPress site URL and click Install PhantomWP plugin
4. Download the per-project zip we prepare for you
5. In WordPress admin, go to Plugins > Add New > Upload Plugin
6. Upload the zip and click Activate
7. Visit the PhantomWP menu in wp-admin once. The plugin self-pairs automatically.

PhantomWP bakes a one-time bootstrap token into the zip. On the first admin visit after activation, the plugin uses that token to pair itself with your PhantomWP project. The token self-destructs after a successful pair.

Option B: Manual installation

If you want to install the WordPress plugin manually without the IDE flow, contact support and we will prepare a build for your site. The pairing still requires a bootstrap token generated per-project, which is why the IDE flow is the recommended path.

Verifying the Connection

After activation and pairing:

1. In WordPress admin, open the PhantomWP menu. You should see:
   • Status: Paired
   • Project ID: your PhantomWP project ID
   • Last check-in timestamp
2. In the PhantomWP IDE, open the WordPress connect panel. The access level should read Full Access instead of Read-only.

If the status shows Not paired, see Troubleshooting below.

What "Full Access" Unlocks

With the WordPress plugin paired, the access level in your PhantomWP project changes from read-only to full. This enables:

Agentic AI Write Access

The PhantomWP AI assistant can now operate your WordPress CMS on your behalf. Ask the assistant things like:

• "Create a Recipes custom post type with fields for ingredients, servings, and prep time."
• "Add a Testimonials CPT with a quote, author, and company logo field."
• "Write a blog post announcing our new pricing page and publish it as a draft."
• "Create an About page in WordPress and pull the copy from the existing Homepage."
• "Add an 'FAQ' taxonomy for categorizing support articles."

Under the hood, the assistant routes these requests through PhantomWP Connect, which creates the posts, pages, CPTs, taxonomies, or field groups directly inside your WordPress.

Visitor JWT Authentication

Your generated Astro frontend gets a full login flow:

• /account/login and /account/register pages
• /account/forgot-password and /account/reset-password pages
• /api/auth/* routes that issue and validate JWTs

Tokens are short-lived (one day by default), capability-restricted (destructive WordPress caps are stripped when a request is JWT-authenticated), and auto-invalidated when the user's role, email, or password changes, or when the account is deleted.

Signed Writes

Any write PhantomWP makes to your WordPress carries an ECDSA P-256 signature with a SHA-256 digest, a timestamp, and a nonce. The signature is scoped to your specific project's install ID and normalized host, so a signature captured on one project cannot be replayed against another.

WooCommerce Customer Flows

Customer login, registration, and account features are handled through the plugin's JWT endpoints. See WooCommerce Setup for the full flow.

Content Modeler Support

The WordPress plugin auto-detects and routes scaffolding through whichever content modeler is installed:

The plugin never installs modelers on your behalf. It detects what you already use.

Security Model

PhantomWP Connect is designed so that the worst case of a stolen token or compromised edge is bounded.

• ECDSA P-256 DER-encoded signatures with SHA-256 digest on every PhantomWP-to-WordPress request.
• Timestamp + nonce replay protection, ±5 minute window.
• Install scope: signatures are bound to your project's wpInstallId and normalized host. Cross-project replay is refused.
• Key separation: PhantomWP holds the signing private key (encrypted at rest with env KEK). WordPress only holds the public key.
• JWT capability stripping: when a request authenticates via JWT, destructive WordPress capabilities are removed for that request.
• Automatic token invalidation on role change, email change, password change, or account deletion.
• AES-256-GCM encryption at rest for sensitive options stored in the WordPress database.
• Kill switch: phantomwp_scaffold_enabled option disables all scaffold endpoints instantly without uninstalling the plugin.

For full edge-hardening guidance (Nginx, Apache, Cloudflare), see WordPress Security.

REST API Endpoints

The WordPress plugin exposes these endpoints under /wp-json/phantomwp/v1/:

Authentication

Scaffolding

Pairing

All write and scaffold routes are gated by the signed API key permission. Public pairing routes are scoped to the one-time bootstrap token.

Uninstalling

You can deactivate or delete PhantomWP Connect at any time. Your WordPress content is untouched, the plugin never moves your posts or data.

When the WordPress plugin is not present:

• Reads still work through the public REST API (if your site allows them)
• Writes from PhantomWP stop working
• AI scaffolding from the PhantomWP IDE stops working
• JWT visitor auth on your Astro site stops working
• WooCommerce customer login on your Astro site stops working

Your Astro repo and all standard content keep working. You do not lose your site.

Troubleshooting

Status shows "Not paired"

1. Confirm the WordPress plugin is active in wp-admin > Plugins.
2. Visit any admin page in wp-admin once. The plugin runs the bootstrap handshake on admin_init.
3. Check your server error log for any pairing errors from PhantomWP_Connect.
4. In the PhantomWP IDE, use Re-pair on the connect card to regenerate a fresh zip and start over.

"No route was found matching the URL and request method"

The plugin is not installed or not activated. Re-check wp-admin > Plugins for PhantomWP Connect.

Writes fail with 403 / signature invalid

1. Your WordPress server's clock is more than 5 minutes off. Fix NTP.
2. The public key on WordPress does not match PhantomWP's private key. Re-pair to refresh.
3. You are behind a reverse proxy that strips the X-PhantomWP-Signature header. Allowlist it.

AI scaffolding says "Scaffolding is disabled"

Open the WordPress admin, go to the PhantomWP menu, and re-enable Scaffolding. This maps to the phantomwp_scaffold_enabled option.

After upgrading from "JWT Authentication for WP REST API"

Old tokens are invalidated. Existing customers need to log in again. This is intentional, the two plugins use different secrets.

Next Steps

• Connecting WordPress - URL-level connection and content import
• WordPress Security - Edge hardening and the access secret
• WooCommerce Setup - Customer login and storefront flows
• Blog: Introducing PhantomWP Connect - The story behind the WordPress plugin