DEV Community: Md. Zubaer Ahammed

Validate AI-Generated Gutenberg Block Markup Before Insert: parse_blocks, Allowlist and Fallback

Md. Zubaer Ahammed — Wed, 11 Nov 2026 02:05:30 +0000

The editor throws This block contains unexpected or invalid content the moment a model's response is pasted into a post — or worse, the block saves without complaint and the front end renders a wall of escaped <div> tags where a two-column layout should be. The REST request returned 200, the JSON parsed, and nothing in debug.log explains how a core/columns block turned into a paragraph of raw HTML.

That gap between "the request succeeded" and "the markup is valid" is where most LLM-to-Gutenberg integrations break. What follows diagnoses the failure, builds a validator around parse_blocks(), and hardens it so the same class of markup cannot reach post_content again.

You need PHP 7.4 or newer, WordPress 6.2 or newer, and a plugin or theme where you can register a REST route. The editor side uses @wordpress/api-fetch and @wordpress/blocks, both already bundled with the block editor, so no extra build tooling is required.

The symptom: a 200 response that still breaks the block editor

A typical failure looks like this. The model returns something close to valid block markup, your endpoint stores it, and the editor shows one of three things:

A red Block validation failed notice on a block that looks correct in the source.
A Classic or HTML block containing the entire response, delimiters and all.
Nothing at all — the post saves, but the front end prints escaped angle brackets.

All three trace back to the same cause: the markup was never parsed into a block tree, so nothing checked whether the block names exist, whether the attributes match the registered schema, or whether freeform HTML was sitting between delimiters. parse_blocks() is a tokeniser, not a validator. It will happily return a block named core/does-not-exist with arbitrary attributes, and it will return raw HTML as a nameless block with a populated innerHTML.

There is a second layer people miss. The editor's own Block validation failed message comes from the JavaScript save() function of each block type, comparing the saved markup to what the block would generate. That check runs in the browser, after the content is already in the database. Server-side validation is not a replacement for it — it is the gate that stops bad markup from ever reaching the point where the browser check matters.

Reproduce the failure with a single parse_blocks() call

Before writing any validation logic, confirm what the parser actually returns for a bad response. Drop this into a scratch plugin or a wp eval call and inspect the output:

<?php
$markup = '<div class="hero">Intro text</div>
<!-- wp:core/columns {"columns":2} -->
<!-- wp:core/column -->
<!-- wp:core/paragraph -->
<p>Hello</p>
<!-- /wp:core/paragraph -->
<!-- /wp:core/column -->
<!-- /wp:core/columns -->';

$blocks = parse_blocks( $markup );

foreach ( $blocks as $block ) {
    printf(
        "name=%s innerHTML=%s\n",
        var_export( $block['blockName'], true ),
        substr( trim( (string) $block['innerHTML'] ), 0, 40 )
    );
}

The first entry has blockName === null and an innerHTML of <div class="hero">Intro text</div>. That is the freeform HTML the model invented. The second entry is core/columns with an attribute the real block does not accept in that shape. Neither of these is an error as far as parse_blocks() is concerned — which is precisely why the failure surfaces later, in the editor, with no useful trace.

Running it on WordPress 7.1.3 with PHP 8.2 prints:

name=NULL innerHTML=<div class="hero">Intro text</div>
name='core/columns' innerHTML=

The core/columns entry has an empty innerHTML because its content lives in innerBlocks, so checking the top-level HTML alone tells you nothing about the nested blocks.

Walk the block tree and collect every name and every freeform chunk

Validation needs two lists: the block names present anywhere in the tree (including nested innerBlocks), and every nameless node that carries HTML. A recursive walker gives you both in one pass and keeps the logic reusable for the REST endpoint and the save-time guard.

<?php
/**
 * Collect block names and freeform HTML from a parsed tree.
 *
 * @param array $blocks   Output of parse_blocks().
 * @param array $names    Accumulator for block names.
 * @param array $freeform Accumulator for raw HTML chunks.
 * @return array{names: string[], freeform: string[]}
 */
function wptut_collect_blocks( array $blocks, array &$names = array(), array &$freeform = array() ): array {
    foreach ( $blocks as $block ) {
        if ( empty( $block['blockName'] ) ) {
            $html = trim( (string) ( $block['innerHTML'] ?? '' ) );
            if ( '' !== $html ) {
                $freeform[] = $html;
            }
        } else {
            $names[] = $block['blockName'];
        }

        if ( ! empty( $block['innerBlocks'] ) ) {
            wptut_collect_blocks( $block['innerBlocks'], $names, $freeform );
        }
    }

    return array( 'names' => $names, 'freeform' => $freeform );
}

Passing the accumulators by reference matters. A model that nests a paragraph inside a column inside columns produces three levels, and a non-recursive check would only see the top one. The freeform list is the more important output: any non-empty entry is a hard reject, because a nameless block means the model wrote HTML outside the delimiter syntax and the editor will treat it as a Classic block.

Build the allowlist from registered block types, not from a hardcoded guess

An allowlist written by hand drifts the moment a plugin registers a new block or a core block is renamed. Query the registry instead, then intersect with the subset you actually want the model to produce. The registry call also gives you the attribute schema for the next step.

<?php
function wptut_validate_block_tree( string $markup, array $allowed ) {
    $blocks    = parse_blocks( $markup );
    $collected = wptut_collect_blocks( $blocks );

    if ( ! empty( $collected['freeform'] ) ) {
        return new WP_Error(
            'wptut_raw_html',
            __( 'Raw HTML was returned outside a block delimiter.', 'wptut' ),
            array( 'freeform' => $collected['freeform'] )
        );
    }

    $registry = WP_Block_Type_Registry::get_instance();
    $unknown  = array();

    foreach ( array_unique( $collected['names'] ) as $name ) {
        if ( ! in_array( $name, $allowed, true ) || ! $registry->is_registered( $name ) ) {
            $unknown[] = $name;
        }
    }

    if ( ! empty( $unknown ) ) {
        return new WP_Error(
            'wptut_unknown_block',
            __( 'Disallowed or unregistered block names were returned.', 'wptut' ),
            array( 'blocks' => $unknown )
        );
    }

    return wptut_sanitise_attributes( $blocks );
}

Checking is_registered() as well as the allowlist catches a subtle case: a block name that is in your list but whose registering plugin has been deactivated. Without that second check the markup passes validation and then renders as an empty comment on the front end. Returning a WP_Error with structured data — rather than a boolean — lets the caller show the model's exact offending names in the diff panel.

Sanitise attributes against block.json so the model cannot smuggle markup

Block attributes are declared in block.json with a type and often an enum or default. The registry exposes that schema through $type->attributes. Casting each value to its declared type and running strings through sanitize_text_field() removes the most common injection route: an attribute like content or caption that a block renders without escaping.

<?php
function wptut_sanitise_attributes( array $blocks ): array {
    $registry = WP_Block_Type_Registry::get_instance();
    $clean    = array();

    foreach ( $blocks as $block ) {
        if ( empty( $block['blockName'] ) ) {
            continue;
        }

        $type = $registry->get_registered( $block['blockName'] );
        if ( ! $type ) {
            continue;
        }

        $schema = is_array( $type->attributes ) ? $type->attributes : array();
        $attrs  = array();

        foreach ( $schema as $name => $definition ) {
            if ( ! array_key_exists( $name, (array) $block['attrs'] ) ) {
                continue;
            }

            $value = $block['attrs'][ $name ];

            switch ( $definition['type'] ?? 'string' ) {
                case 'boolean':
                    $attrs[ $name ] = (bool) $value;
                    break;
                case 'integer':
                    $attrs[ $name ] = (int) $value;
                    break;
                case 'number':
                    $attrs[ $name ] = (float) $value;
                    break;
                case 'array':
                case 'object':
                    $attrs[ $name ] = array_map( 'sanitize_text_field', (array) $value );
                    break;
                default:
                    $attrs[ $name ] = sanitize_text_field( (string) $value );
            }
        }

        $clean[] = array(
            'blockName'   => $block['blockName'],
            'attrs'       => $attrs,
            'innerBlocks' => wptut_sanitise_attributes( $block['innerBlocks'] ?? array() ),
            'innerHTML'   => wp_kses_post( $block['innerHTML'] ?? '' ),
        );
    }

    return $clean;
}

Two details carry the security weight. First, attributes not present in the schema are dropped entirely — a model that invents "onclick" or "style" gets nothing back. Second, wp_kses_post() on innerHTML keeps the paragraph and heading tags a block legitimately needs while stripping <script>, event handlers and javascript: URLs. Do not reach for strip_tags() here; it will flatten a core/paragraph into plain text and break the block's own save() output.

Register a REST endpoint that reports the diff instead of inserting blindly

The endpoint should always return 200 with a structured report, not a 400. A validation failure is an expected outcome of an LLM pipeline, and a non-error status keeps the editor's apiFetch promise resolving so the sidebar can render the reason and the fallback in one pass.

<?php
add_action( 'rest_api_init', function () {
    register_rest_route( 'wptut/v1', '/validate-blocks', array(
        'methods'             => 'POST',
        'permission_callback' => function () {
            return current_user_can( 'edit_posts' );
        },
        'args' => array(
            'markup' => array( 'required' => true, 'type' => 'string' ),
        ),
        'callback' => function ( WP_REST_Request $request ) {
            $allowed = array(
                'core/paragraph', 'core/heading', 'core/list', 'core/list-item',
                'core/quote', 'core/image', 'core/buttons', 'core/button',
            );

            $markup = (string) $request['markup'];
            $result = wptut_validate_block_tree( $markup, $allowed );

            if ( is_wp_error( $result ) ) {
                return new WP_REST_Response( array(
                    'valid'    => false,
                    'code'     => $result->get_error_code(),
                    'message'  => $result->get_error_message(),
                    'data'     => $result->get_error_data(),
                    'fallback' => wptut_fallback_markup( $markup ),
                ), 200 );
            }

            return new WP_REST_Response( array(
                'valid'  => true,
                'blocks' => $result,
                'diff'   => wptut_diff_markup( $markup, $result ),
            ), 200 );
        },
    ) );
} );

The diff is a line-by-line comparison of the original markup against serialize_blocks() of the cleaned tree. It is deliberately coarse — the point is to show a human which attribute changed, not to produce a merge tool. A simple loop over preg_split( '/\R/', ... ) is enough and avoids pulling in the admin diff renderer.

Fall back to core/paragraph with the model's text intact

Rejecting outright loses whatever the model got right. Stripping the delimiters, flattening the tags and wrapping the remaining text in a single core/paragraph preserves the prose while guaranteeing the result is a block the editor can render. serialize_blocks() produces the delimiter comments for you, so the fallback is valid Gutenberg markup rather than a hand-built string.

<?php
function wptut_fallback_markup( string $markup ): string {
    $text = preg_replace( '/<!--\s*\/?wp:.*?-->/s', '', $markup );
    $text = wp_strip_all_tags( (string) $text );
    $text = trim( preg_replace( '/\s+/u', ' ', $text ) );

    if ( '' === $text ) {
        return '';
    }

    $html = '<p>' . esc_html( $text ) . '</p>';

    return serialize_blocks( array(
        array(
            'blockName'    => 'core/paragraph',
            'attrs'        => array(),
            'innerBlocks'  => array(),
            'innerHTML'    => $html,
            'innerContent' => array( $html ),
        ),
    ) );
}

Note the innerContent key. serialize_blocks() relies on it to decide where child blocks and text fragments sit; omitting it produces a block that parses back with an empty body. If the fallback also comes back empty — the model returned only markup and no prose — return an empty string and let the caller show "nothing to insert" rather than writing a blank paragraph.

Show the diff in a Gutenberg sidebar before anything touches the post

The sidebar is where the pipeline becomes trustworthy. It calls the endpoint, renders the rejection reason or the diff, and only calls insertBlocks() after a human clicks. parse() from @wordpress/blocks turns the chosen source — validated markup or fallback — into block objects the editor can insert directly.

import { useState } from '@wordpress/element';
import { useDispatch } from '@wordpress/data';
import { store as blockEditorStore } from '@wordpress/block-editor';
import { parse } from '@wordpress/blocks';
import apiFetch from '@wordpress/api-fetch';

export function AiMarkupPanel( { markup } ) {
    const [ report, setReport ] = useState( null );
    const { insertBlocks } = useDispatch( blockEditorStore );

    async function validate() {
        const response = await apiFetch( {
            path: '/wptut/v1/validate-blocks',
            method: 'POST',
            data: { markup },
        } );
        setReport( response );
    }

    function insert() {
        const source = report.valid ? markup : report.fallback;
        if ( ! source ) {
            return;
        }
        insertBlocks( parse( source ) );
    }

    return (
        <div className="wptut-ai-panel">
            <button onClick={ validate }>Validate markup</button>
            { report && (
                <p className={ report.valid ? 'is-valid' : 'is-invalid' }>
                    { report.valid ? 'All blocks passed.' : report.message }
                </p>
            ) }
            { report && report.diff && report.diff.length > 0 && (
                <ol className="wptut-diff">
                    { report.diff.map( ( row ) => (
                        <li key={ row.line }>
                            <del>{ row.before }</del>
                            <ins>{ row.after }</ins>
                        </li>
                    ) ) }
                </ol>
            ) }
            <button onClick={ insert } disabled={ ! report }>
                Insert { report && report.valid ? 'validated blocks' : 'fallback paragraph' }
            </button>
        </div>
    );
}

Keep the insert button disabled until report exists. That single guard is what stops a fast click from bypassing validation entirely, and it makes the fallback path an explicit choice rather than a silent substitution.

Close the loop: reject at save time as well as at insert time

An editor-side check only covers the path you wrote. A second client, a cron job or a direct wp_insert_post() call can still write unvalidated markup. Add a save-time guard, but gate it behind a flag so it never rewrites hand-authored posts that legitimately use blocks outside your allowlist.

<?php
add_filter( 'wp_insert_post_data', function ( $data, $postarr ) {
    if ( empty( $postarr['ID'] ) || ! get_post_meta( $postarr['ID'], '_wptut_ai_generated', true ) ) {
        return $data;
    }

    $allowed = array( 'core/paragraph', 'core/heading', 'core/list', 'core/list-item', 'core/quote' );
    $result  = wptut_validate_block_tree( (string) $data['post_content'], $allowed );

    if ( is_wp_error( $result ) ) {
        $data['post_content'] = wptut_fallback_markup( (string) $data['post_content'] );
    }

    return $data;
}, 10, 2 );

The meta flag is the whole safety mechanism. Without it, this filter runs on every save in the site and quietly flattens any post containing a block you did not list — including ones a human built by hand in the editor. Set _wptut_ai_generated when the pipeline creates the post, and clear it the first time a human edits the content.

One more hardening step worth taking: log every rejection with the model name, the error code and the offending block names, using error_log() or a custom table. Patterns emerge quickly — a model that keeps emitting core/group when your allowlist stops at core/columns is telling you something about its training data, and the fix is usually a tighter system prompt rather than a wider allowlist.

A useful next experiment is to feed the rejection payload back to the model automatically: take the code and data.blocks from the failed response, append them to the original prompt as a correction instruction, and retry once before falling back. A single retry can fix small markup mistakes, and the paragraph fallback stays as the final safety net.

Originally published on WP Tuts Hub.

Harden WordPress Application Passwords: Per-Role Availability, Revocation on Role Change and Auth Logging

Md. Zubaer Ahammed — Wed, 11 Nov 2026 02:05:12 +0000

Why application passwords deserve their own hardening pass

Application passwords are core WordPress functionality. Since 5.6 the feature ships enabled, letting any user with profile access mint a per-application credential that authenticates over HTTP Basic against the REST API and XML-RPC. That makes headless front ends, deploy pipelines, Zapier workflows and mobile apps trivial to wire up — and it also means a stolen string in a CI log is a full user session that never expires.

Out of the box the feature has four gaps worth closing:

Every role can create one. A subscriber can generate a credential and probe the REST API with it.
Nothing revokes them. Demote an editor to subscriber and their application password keeps working indefinitely.
They bypass two-factor plugins that only hook the login form, because authentication happens on the authenticate filter, not the login screen.
There is no audit trail. Core stores only last_used and last_ip on each item, which tells you nothing about failed attempts.

This tutorial builds a single mu-plugin that closes all four and adds a WP-CLI command for auditing and bulk revocation. Recent WordPress versions store application passwords hashed rather than in plain text, so a leaked database backup no longer hands over working credentials — but a leaked credential from anywhere else still does, which is exactly why the controls below matter.

Prerequisites

WordPress 6.4 or newer. The hooks used here have been stable since 5.6, but wp_get_environment_type() and the modern admin notice patterns are cleaner on recent releases.
PHP 8.1 or newer.
A site served over HTTPS with a valid certificate. Step 2 refuses to work without it.
WP-CLI 2.8+ for Step 5.
Write access to wp-content/mu-plugins/.

Create wp-content/mu-plugins/app-password-guard.php and paste each block into it as you go. Must-use plugins load before regular plugins, cannot be deactivated by an admin who is mid-incident, and are always loaded by WP-CLI — which matters for Step 5.

How the availability gate actually works

Two filters control the feature:

wp_is_application_passwords_available — a global boolean. Return false and the whole feature is off site-wide.
wp_is_application_passwords_available_for_user — receives $available and the WP_User object. This gates creation through the REST controller and the profile UI.

One thing to internalise before you write a line of code: the per-user filter is a gate, not a revocation mechanism. It governs who may create a password and who sees the UI. It does not retroactively invalidate credentials already sitting in wp_usermeta. That distinction is why Step 3 exists and why filtering alone gives a false sense of security.

Step 1 — Allow only named roles

Start by narrowing who can create credentials at all. Use a capability check rather than a role check if you have custom roles with granular permissions; the example below uses roles because that is what the brief calls for.

<?php
/**
 * Plugin Name: App Password Guard
 * Description: Restricts application passwords to named roles.
 */

add_filter(
    'wp_is_application_passwords_available_for_user',
    static function ( $available, $user ) {
        if ( ! $available ) {
            return false;
        }

        $allowed = array( 'administrator', 'editor', 'api_client' );

        return (bool) array_intersect( $allowed, (array) $user->roles );
    },
    10,
    2
);

Why this shape: returning false early preserves any other plugin's decision to disable the feature entirely. array_intersect() handles multi-role users correctly, which a naive in_array( $user->roles[0], ... ) does not. Keep administrator in the list or you will lock yourself out of your own deploy scripts; add a dedicated low-privilege role such as api_client for machine accounts so integration credentials never belong to a human administrator.

Step 2 — Refuse to work over plain HTTP

HTTP Basic authentication base64-encodes credentials, it does not encrypt them. Over plain HTTP anyone on the path can replay the header. Disable the feature globally when TLS is absent.

<?php
add_filter(
    'wp_is_application_passwords_available',
    static function ( $available ) {
        if ( is_ssl() ) {
            return $available;
        }

        // Allow plain HTTP only on disposable local environments.
        if ( 'local' === wp_get_environment_type() ) {
            return $available;
        }

        return false;
    }
);

add_action(
    'admin_notices',
    static function () {
        if ( is_ssl() || ! current_user_can( 'manage_options' ) ) {
            return;
        }

        printf(
            '<div class="notice notice-error"><p>%s</p></div>',
            esc_html__( 'Application passwords are disabled because this site is not served over HTTPS.', 'app-pass-guard' )
        );
    }
);

Why the environment check: local development over http://localhost is legitimate and you do not want to break every developer's tooling. wp_get_environment_type() reads WP_ENVIRONMENT_TYPE, so a staging site that accidentally inherits local still gets protected as long as you set the constant correctly.

Behind a reverse proxy, TLS terminates upstream and is_ssl() returns false even though visitors are on HTTPS. Fix that in wp-config.php before deploying this filter, or you will silently disable every integration on the site:

<?php
// wp-config.php — only when a trusted proxy terminates TLS.
if ( isset( $_SERVER['HTTP_X_FORWARDED_PROTO'] ) && 'https' === $_SERVER['HTTP_X_FORWARDED_PROTO'] ) {
    $_SERVER['HTTPS'] = 'on';
}

Step 3 — Revoke on role change

Now the important one. When a user loses the role that justified their credential, every stored password must go.

<?php
/**
 * Revoke application passwords a user no longer qualifies for.
 */
function app_pass_guard_revoke_for_user( $user_id ) {
    $user = get_userdata( $user_id );

    if ( ! $user ) {
        return;
    }

    $allowed = array( 'administrator', 'editor', 'api_client' );

    if ( array_intersect( $allowed, (array) $user->roles ) ) {
        return;
    }

    $passwords = WP_Application_Passwords::get_user_application_passwords( $user_id );

    foreach ( $passwords as $item ) {
        WP_Application_Passwords::delete_application_password( $user_id, $item['uuid'] );
    }

    if ( $passwords ) {
        do_action( 'app_pass_guard_revoked', $user_id, count( $passwords ) );
    }
}

add_action( 'set_user_role', 'app_pass_guard_revoke_for_user' );
add_action( 'add_user_role', 'app_pass_guard_revoke_for_user' );
add_action( 'remove_user_role', 'app_pass_guard_revoke_for_user' );

Why three hooks: set_user_role fires only when WP_User::set_role() runs, which replaces all roles at once. Sites using multiple simultaneous roles call add_role() and remove_role() instead, firing add_user_role and remove_user_role. Hooking all three and re-evaluating inside the callback covers every path the WordPress API offers.

Why the check is inside the callback: add_user_role fires when a role is added, which may leave the user still eligible. Re-checking rather than assuming keeps the logic correct in both directions.

Reuse the same $allowed array from Step 1 — better still, define it once as a constant so the two lists cannot drift apart:

<?php
define( 'APP_PASS_GUARD_ROLES', array( 'administrator', 'editor', 'api_client' ) );

Step 4 — Log every success and failure

Core exposes two actions and one filter for this. application_password_did_authenticate passes $user and the password $item. application_password_failed_authentication passes only a WP_Error — no username — so you have to capture the attempted login earlier on the authenticate filter.

First, the storage table. Create it on activation with dbDelta():

<?php
register_activation_hook( __FILE__, static function () {
    global $wpdb;

    require_once ABSPATH . 'wp-admin/includes/upgrade.php';

    $table   = $wpdb->prefix . 'app_pass_log';
    $collate = $wpdb->get_charset_collate();

    $sql = "CREATE TABLE {$table} (
        id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
        created_at DATETIME NOT NULL,
        outcome VARCHAR(10) NOT NULL,
        user_id BIGINT UNSIGNED NOT NULL DEFAULT 0,
        login VARCHAR(60) NOT NULL DEFAULT '',
        uuid CHAR(36) NOT NULL DEFAULT '',
        ip VARCHAR(45) NOT NULL DEFAULT '',
        user_agent VARCHAR(255) NOT NULL DEFAULT '',
        reason VARCHAR(64) NOT NULL DEFAULT '',
        PRIMARY KEY (id),
        KEY user_id (user_id),
        KEY outcome (outcome),
        KEY created_at (created_at)
    ) {$collate};";

    dbDelta( $sql );
} );

Because this is a mu-plugin, register_activation_hook() never fires. Either run the SQL once by hand, or guard the block behind a version option check on plugins_loaded.

Then the logger itself:

<?php
final class App_Pass_Logger {

    private static string $attempted_login = '';

    public static function init() {
        add_filter( 'authenticate', array( __CLASS__, 'capture_login' ), 9, 3 );
        add_action( 'application_password_did_authenticate', array( __CLASS__, 'log_success' ), 10, 2 );
        add_action( 'application_password_failed_authentication', array( __CLASS__, 'log_failure' ) );
    }

    public static function capture_login( $user, $username, $password ) {
        self::$attempted_login = is_string( $username ) ? $username : '';
        return $user;
    }

    public static function log_success( $user, $item ) {
        self::write( 'success', (int) $user->ID, $item['uuid'] ?? '' );
    }

    public static function log_failure( $error ) {
        $reason = $error instanceof WP_Error ? $error->get_error_code() : '';
        self::write( 'failure', 0, '', $reason );
    }

    private static function write( $outcome, $user_id, $uuid, $reason = '' ) {
        global $wpdb;

        $wpdb->insert(
            $wpdb->prefix . 'app_pass_log',
            array(
                'created_at' => gmdate( 'Y-m-d H:i:s' ),
                'outcome'    => $outcome,
                'user_id'    => $user_id,
                'login'      => substr( self::$attempted_login, 0, 60 ),
                'uuid'       => $uuid,
                'ip'         => self::client_ip(),
                'user_agent' => substr( (string) ( $_SERVER['HTTP_USER_AGENT'] ?? '' ), 0, 255 ),
                'reason'     => $reason,
            ),
            array( '%s', '%s', '%d', '%s', '%s', '%s', '%s', '%s' )
        );
    }

    private static function client_ip() {
        $ip = $_SERVER['REMOTE_ADDR'] ?? '';
        return filter_var( $ip, FILTER_VALIDATE_IP ) ? $ip : '';
    }
}

App_Pass_Logger::init();

Why REMOTE_ADDR and nothing else: X-Forwarded-For is attacker-controlled unless you sit behind a proxy you own. Logging a spoofable header into a security table is worse than logging nothing, because it invites bad conclusions during incident review. If you do run a trusted proxy, whitelist its IP range before reading the header.

Why the UUID column: it ties a successful authentication back to the exact credential, so you can correlate with the profile UI and revoke precisely one item rather than all of them. Note that core already maintains last_used and last_ip on the password item itself — this table adds the failure history and the retention policy core does not give you.

Prune the table on a schedule so it does not grow without bound:

DELETE FROM wp_app_pass_log WHERE created_at < DATE_SUB( UTC_TIMESTAMP(), INTERVAL 90 DAY );

Step 5 — WP-CLI list and revoke

Core already ships wp user application-password list|create|delete|get, which works per user. What it does not do is answer "which credentials exist across the whole site, and which ones belong to people who no longer have the role?" Add a command for that.

<?php
if ( defined( 'WP_CLI' ) && WP_CLI ) {
    WP_CLI::add_command( 'app-pass', 'App_Pass_CLI' );
}

class App_Pass_CLI {

    /**
     * Lists application passwords across users.
     *
     * ## OPTIONS
     *
     * [--user=<login>]
     * : Limit to one user.
     *
     * [--role=<role>]
     * : Limit to users holding a role.
     *
     * [--format=<format>]
     * : table, csv or json.
     * ---
     * default: table
     * ---
     */
    public function list( $args, $assoc_args ) {
        $query = array( 'fields' => array( 'ID', 'user_login' ) );

        if ( ! empty( $assoc_args['role'] ) ) {
            $query['role'] = $assoc_args['role'];
        }

        if ( ! empty( $assoc_args['user'] ) ) {
            $user = get_user_by( 'login', $assoc_args['user'] );

            if ( ! $user ) {
                WP_CLI::error( 'No such user.' );
            }

            $query['include'] = array( $user->ID );
        }

        $rows = array();

        foreach ( get_users( $query ) as $user ) {
            foreach ( WP_Application_Passwords::get_user_application_passwords( $user->ID ) as $item ) {
                $rows[] = array(
                    'user_id'    => $user->ID,
                    'user_login' => $user->user_login,
                    'name'       => $item['name'],
                    'uuid'       => $item['uuid'],
                    'created'    => gmdate( 'c', $item['created'] ),
                    'last_used'  => $item['last_used'] ? human_time_diff( $item['last_used'] ) . ' ago' : 'never',
                    'last_ip'    => $item['last_ip'] ?: '',
                );
            }
        }

        WP_CLI\Utils\format_items(
            $assoc_args['format'],
            $rows,
            array( 'user_id', 'user_login', 'name', 'uuid', 'created', 'last_used', 'last_ip' )
        );
    }

    /**
     * Revokes application passwords.
     *
     * ## OPTIONS
     *
     * --user=<login>
     * : Target user.
     *
     * [--uuid=<uuid>]
     * : Revoke one credential only.
     *
     * [--yes]
     * : Skip confirmation.
     */
    public function revoke( $args, $assoc_args ) {
        $user = get_user_by( 'login', $assoc_args['user'] );

        if ( ! $user ) {
            WP_CLI::error( 'No such user.' );
        }

        $passwords = WP_Application_Passwords::get_user_application_passwords( $user->ID );

        if ( ! empty( $assoc_args['uuid'] ) ) {
            $passwords = array_values(
                array_filter(
                    $passwords,
                    static fn( $item ) => $item['uuid'] === $assoc_args['uuid']
                )
            );
        }

        if ( ! $passwords ) {
            WP_CLI::warning( 'Nothing to revoke.' );
            return;
        }

        WP_CLI::confirm(
            sprintf( 'Revoke %d application password(s) for %s?', count( $passwords ), $user->user_login ),
            $assoc_args
        );

        $done = 0;

        foreach ( $passwords as $item ) {
            if ( WP_Application_Passwords::delete_application_password( $user->ID, $item['uuid'] ) ) {
                $done++;
            }
        }

        WP_CLI::success( sprintf( 'Revoked %d application password(s).', $done ) );
    }
}

Usage from the server:

# Everything on the site, oldest first, as CSV for a spreadsheet.
wp app-pass list --format=csv

# Just the integrations team.
wp app-pass list --role=api_client

# One credential, machine readable.
wp app-pass list --user=deploy --format=json

# Kill every credential for a departing contractor.
wp app-pass revoke --user=deploy --yes

# Kill exactly one, keeping the rest alive.
wp app-pass revoke --user=deploy --uuid=8f1c2a4e-0b7d-4f3a-9c55-1d2e3f4a5b6c --yes

Troubleshooting

The Application Passwords section vanished from the profile screen. Either the site is not on HTTPS, or your per-user filter is returning false for that role. Check is_ssl() first — a proxy terminating TLS is the usual culprit.
A valid credential returns 401. The global wp_is_application_passwords_available filter is probably returning false, or the request is not reaching a context where application_password_is_api_request evaluates to true. Application passwords only authenticate on REST and XML-RPC requests.
Log rows are empty on success. application_password_did_authenticate fires only when the request was not already authenticated by cookie or a prior filter at an earlier priority. Test with a clean client, not a logged-in browser.
Revocation did not fire on a role change. Bulk role edits run through direct wp_usermeta writes, and some migration plugins call $wpdb->update() instead of set_role(). Neither fires any hook. Add a nightly sweep that re-runs app_pass_guard_revoke_for_user() against every user ID to catch drift.
wp app-pass reports an unknown command. The mu-plugin must be present and readable by the WP-CLI user. Confirm with wp eval 'var_dump( class_exists( "App_Pass_CLI" ) );'.
dbDelta() silently creates nothing. It requires two spaces after PRIMARY KEY, lowercase types and one field per line. Copy the SQL above verbatim rather than reformatting it.

Next steps

Rate-limit failures. Count rows in wp_app_pass_log per IP over five minutes and return a WP_Error from the authenticate filter once a threshold is crossed. That turns the log from a record into a control.
Expire credentials automatically. Schedule an event that revokes any password whose created timestamp is older than 90 days, and email the owner a week beforehand.
Alert on IP changes. Compare last_ip against the logged ip and notify the site admin when a credential authenticates from a new address.
Surface the log in wp-admin. A WP_List_Table subclass under Tools gives non-CLI admins the same visibility, with the same capability check as the profile screen.
Pair it with two-factor. Application passwords deliberately skip 2FA. Restricting them to a machine-only role and revoking on role change is the substitute for the second factor.

Read the reference pages for wp_is_application_passwords_available_for_user, the WP_Application_Passwords class, and the application_password_did_authenticate action before adapting any of this.

Originally published on WP Tuts Hub.

Build a Streaming WordPress AI Chat Assistant: SSE Endpoint, Conversation Table and Per-User Rate Limits

Md. Zubaer Ahammed — Wed, 11 Nov 2026 02:04:58 +0000

Streaming chat feels fast because the browser paints tokens as they arrive. In WordPress, that means a REST route that keeps the connection open, a server-side proxy to OpenAI, and a client that reads the response body incrementally. The hard parts are not the UI. They are authorisation, persistence, rate limiting and output handling. This tutorial builds a small plugin that does all four without trusting the model.

Prerequisites and guardrails

You need WordPress 6.5 or later, PHP 8.1 or later, the cURL extension, HTTPS, and an OpenAI API key. You also need to edit wp-config.php and activate a plugin so the custom tables are created. A Redis object cache is optional, but useful if you later move quota checks into atomic cache operations.

Do not expose the API key to the browser. All OpenAI calls happen server-side.
Require a nonce and a logged-in user. The nonce stops cross-site request forgery; the login requirement makes per-user quotas meaningful.
Treat model output as untrusted text. The client uses textContent, not innerHTML. The server sanitises the final assistant message before storage.
Add a kill switch. A constant in wp-config.php can disable the feature without a deployment.

What you are building

The browser sends a POST request to /wp-json/wptuts-ai/v1/chat with an X-WP-Nonce header. The route uses a permission_callback to check the nonce, the kill switch and the user capability. The callback reserves quota, stores the user message, calls OpenAI with cURL, and re-emits the upstream Server-Sent Events as event: delta messages. When the stream ends, the assistant message is sanitised, stored, and the token reservation is adjusted.

The custom conversation table keeps messages out of post meta. The usage table makes request and token limits atomic. The examples use 20 requests and 20,000 tokens per user per day, and 60 requests and 60,000 tokens per IP per day. Tune those numbers for your audience and model.

Step 1: Create the plugin and tables

Start with a plugin that creates two tables on activation. The messages table stores the conversation transcript. The usage table stores daily counters keyed by scope and scope key. The unique key on scope, scope_key, window_start is what makes the quota update safe under concurrency.

<?php
/**
 * Plugin Name: WP Tuts AI Chat
 * Description: Streaming AI chat with SSE, conversation storage and quotas.
 */
defined('ABSPATH') || exit;

if ( defined('WPTUTS_AI_CHAT_DISABLED') && WPTUTS_AI_CHAT_DISABLED ) {
    return;
}

register_activation_hook(__FILE__, 'wptuts_ai_install');

function wptuts_ai_install() {
    global $wpdb;
    require_once ABSPATH . 'wp-admin/includes/upgrade.php';
    $charset  = $wpdb->get_charset_collate();
    $messages = $wpdb->prefix . 'wptuts_ai_messages';
    $usage    = $wpdb->prefix . 'wptuts_ai_usage';

    $sql = 'CREATE TABLE ' . $messages . ' (
        id bigint unsigned NOT NULL AUTO_INCREMENT,
        conversation_id char(36) NOT NULL,
        user_id bigint unsigned NOT NULL DEFAULT 0,
        role varchar(16) NOT NULL,
        content longtext NOT NULL,
        token_count int unsigned NOT NULL DEFAULT 0,
        created_at datetime NOT NULL,
        PRIMARY KEY  (id),
        KEY conversation (conversation_id, id),
        KEY user_created (user_id, created_at)
    ) ' . $charset . ';

    CREATE TABLE ' . $usage . ' (
        id bigint unsigned NOT NULL AUTO_INCREMENT,
        scope varchar(8) NOT NULL,
        scope_key varchar(64) NOT NULL,
        window_start datetime NOT NULL,
        requests int unsigned NOT NULL DEFAULT 0,
        tokens int unsigned NOT NULL DEFAULT 0,
        PRIMARY KEY  (id),
        UNIQUE KEY scope_window (scope, scope_key, window_start)
    ) ' . $charset . ';';

    dbDelta($sql);
}

The conversation_id is a UUID generated by WordPress. The role column stores user or assistant. The token_count column is filled from the upstream usage block when available. The usage table uses a daily UTC window; using UTC avoids daylight-saving edge cases.

Step 2: Register the nonce-protected REST route

Use register_rest_route() with a permission_callback. The permission callback runs before the streaming callback, so it is the right place to reject disabled, unauthenticated or nonce-less requests. The nonce action is wp_rest, which is the same nonce WordPress uses for the REST API.

add_action('rest_api_init', function () {
    register_rest_route('wptuts-ai/v1', '/chat', [
        'methods'             => 'POST',
        'callback'            => 'wptuts_ai_chat_stream',
        'permission_callback' => 'wptuts_ai_chat_permissions',
        'args'                => [
            'message' => [
                'required'          => true,
                'type'              => 'string',
                'sanitize_callback' => 'sanitize_textarea_field',
            ],
            'conversation_id' => [
                'required'          => false,
                'type'              => 'string',
                'sanitize_callback' => 'sanitize_text_field',
            ],
        ],
    ]);
});

function wptuts_ai_chat_permissions( WP_REST_Request $request ) {
    if ( defined('WPTUTS_AI_CHAT_DISABLED') && WPTUTS_AI_CHAT_DISABLED ) {
        return new WP_Error('wptuts_ai_disabled', 'Chat is disabled.', ['status' => 503]);
    }
    $nonce = $request->get_header('X-WP-Nonce');
    if ( ! $nonce || ! wp_verify_nonce($nonce, 'wp_rest') ) {
        return new WP_Error('wptuts_ai_nonce', 'Invalid nonce.', ['status' => 403]);
    }
    if ( ! is_user_logged_in() || ! current_user_can('read') ) {
        return new WP_Error('wptuts_ai_auth', 'Login required.', ['status' => 401]);
    }
    return true;
}

function wptuts_ai_ip_hash() {
    $ip = isset($_SERVER['REMOTE_ADDR']) ? sanitize_text_field(wp_unslash($_SERVER['REMOTE_ADDR'])) : '';
    return hash_hmac('sha256', $ip, wp_salt('nonce'));
}

function wptuts_ai_reserve_quota( $user_id, $ip_hash, $max_tokens ) {
    global $wpdb;
    $table  = $wpdb->prefix . 'wptuts_ai_usage';
    $window = gmdate('Y-m-d 00:00:00');
    $limits = [
        'user' => ['requests' => 20, 'tokens' => 20000],
        'ip'   => ['requests' => 60, 'tokens' => 60000],
    ];
    $scopes = [
        'user' => (string) $user_id,
        'ip'   => $ip_hash,
    ];

    $wpdb->query('START TRANSACTION');
    foreach ( $scopes as $scope => $key ) {
        $wpdb->query($wpdb->prepare(
            'INSERT INTO ' . $table . ' (scope, scope_key, window_start, requests, tokens)
             VALUES (%s, %s, %s, 0, 0)
             ON DUPLICATE KEY UPDATE id = id',
            $scope, $key, $window
        ));
        $row = $wpdb->get_row($wpdb->prepare(
            'SELECT requests, tokens FROM ' . $table . '
             WHERE scope = %s AND scope_key = %s AND window_start = %s FOR UPDATE',
            $scope, $key, $window
        ));
        if ( ! $row || (int) $row->requests + 1 > $limits[$scope]['requests'] || (int) $row->tokens + $max_tokens > $limits[$scope]['tokens'] ) {
            $wpdb->query('ROLLBACK');
            return new WP_Error('wptuts_ai_quota', 'Rate limit or token budget exceeded.', ['status' => 429]);
        }
    }
    foreach ( $scopes as $scope => $key ) {
        $wpdb->query($wpdb->prepare(
            'UPDATE ' . $table . ' SET requests = requests + 1, tokens = tokens + %d
             WHERE scope = %s AND scope_key = %s AND window_start = %s',
            $max_tokens, $scope, $key, $window
        ));
    }
    $wpdb->query('COMMIT');
    return true;
}

The quota function uses a transaction and SELECT ... FOR UPDATE so two concurrent requests cannot both pass the same limit. It reserves the maximum token count before the upstream call, then wptuts_ai_adjust_tokens() corrects the reservation when the real usage arrives. If you run on a platform where transactions are unreliable, move the counters to Redis with atomic increments and a fixed window.

Step 3: Stream SSE from OpenAI to the browser

WordPress HTTP API helpers buffer the response, which defeats streaming. Use cURL with CURLOPT_WRITEFUNCTION to forward chunks as they arrive. The server sends its own SSE frames to the browser, so the client never sees the OpenAI key or the upstream response shape.

function wptuts_ai_chat_stream( WP_REST_Request $request ) {
    if ( defined('WPTUTS_AI_CHAT_DISABLED') && WPTUTS_AI_CHAT_DISABLED ) {
        return new WP_Error('wptuts_ai_disabled', 'Chat is disabled.', ['status' => 503]);
    }

    $user_id = get_current_user_id();
    $ip_hash = wptuts_ai_ip_hash();
    $message = $request->get_param('message');
    $message = is_string($message) ? trim($message) : '';
    if ( '' === $message || mb_strlen($message) > 2000 ) {
        return new WP_Error('wptuts_ai_message', 'Message must be 1-2000 characters.', ['status' => 400]);
    }

    $conversation_id = $request->get_param('conversation_id');
    if ( ! $conversation_id || ! wp_is_uuid($conversation_id) ) {
        $conversation_id = wp_generate_uuid4();
    }

    $max_tokens = 512;
    $quota = wptuts_ai_reserve_quota($user_id, $ip_hash, $max_tokens);
    if ( is_wp_error($quota) ) {
        return $quota;
    }

    wptuts_ai_store_message($conversation_id, $user_id, 'user', $message, 0);
    $history = wptuts_ai_get_history($conversation_id, $user_id, 10);
    $messages = array_merge(
        [['role' => 'system', 'content' => 'You are a concise WordPress support assistant. Never output HTML.']],
        $history
    );

    wptuts_ai_sse_headers();
    wptuts_ai_sse_event('meta', ['conversation_id' => $conversation_id]);
    wptuts_ai_stream_openai($messages, $conversation_id, $user_id, $max_tokens, $max_tokens);
    exit;
}

function wptuts_ai_sse_headers() {
    if ( function_exists('apache_setenv') ) {
        @apache_setenv('no-gzip', '1');
    }
    @ini_set('zlib.output_compression', '0');
    @ini_set('output_buffering', '0');
    while ( ob_get_level() > 0 ) {
        @ob_end_flush();
    }
    header('Content-Type: text/event-stream; charset=utf-8');
    header('Cache-Control: no-cache, no-store, must-revalidate');
    header('X-Accel-Buffering: no');
    header('Connection: keep-alive');
    status_header(200);
}

function wptuts_ai_sse_event( $event, array $data ) {
    echo 'event: ' . $event . chr(10);
    echo 'data: ' . wp_json_encode($data) . chr(10) . chr(10);
    @ob_flush();
    flush();
}

Disable compression and output buffering before sending headers. The X-Accel-Buffering: no header is important on Nginx. The meta event gives the client the conversation ID. The delta event carries text. The done event carries the final token count. If cURL fails, send an error event and still close the stream cleanly.

function wptuts_ai_stream_openai( array $messages, $conversation_id, $user_id, $max_tokens, $reserved ) {
    $api_key = defined('WPTUTS_OPENAI_API_KEY') ? WPTUTS_OPENAI_API_KEY : '';
    if ( ! $api_key ) {
        wptuts_ai_sse_event('error', ['message' => 'Missing API key.']);
        return;
    }

    $payload = wp_json_encode([
        'model'          => 'gpt-4o-mini',
        'messages'       => $messages,
        'max_tokens'     => $max_tokens,
        'stream'         => true,
        'stream_options' => ['include_usage' => true],
    ]);

    $buffer = '';
    $assistant = '';
    $used = 0;

    $ch = curl_init('https://api.openai.com/v1/chat/completions');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . $api_key,
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS     => $payload,
        CURLOPT_RETURNTRANSFER => false,
        CURLOPT_TIMEOUT        => 60,
        CURLOPT_WRITEFUNCTION  => function ( $ch, $chunk ) use ( &$buffer, &$assistant, &$used ) {
            $buffer .= $chunk;
            while ( false !== ( $pos = strpos($buffer, chr(10)) ) ) {
                $line = trim(substr($buffer, 0, $pos));
                $buffer = substr($buffer, $pos + 1);
                if ( '' === $line || 0 !== strpos($line, 'data: ') ) {
                    continue;
                }
                $data = substr($line, 6);
                if ( '[DONE]' === $data ) {
                    continue;
                }
                $json = json_decode($data, true);
                if ( isset($json['choices'][0]['delta']['content']) ) {
                    $delta = $json['choices'][0]['delta']['content'];
                    $assistant .= $delta;
                    wptuts_ai_sse_event('delta', ['text' => $delta]);
                }
                if ( isset($json['usage']['total_tokens']) ) {
                    $used = (int) $json['usage']['total_tokens'];
                }
            }
            return strlen($chunk);
        },
    ]);

    curl_exec($ch);
    $errno = curl_errno($ch);
    curl_close($ch);

    if ( $errno ) {
        wptuts_ai_sse_event('error', ['message' => 'Upstream request failed.']);
    }

    if ( $used < 1 ) {
        $used = $reserved;
    }

    $assistant = sanitize_textarea_field($assistant);
    wptuts_ai_store_message($conversation_id, $user_id, 'assistant', $assistant, $used);
    wptuts_ai_adjust_tokens($user_id, wptuts_ai_ip_hash(), $reserved, $used);
    wptuts_ai_sse_event('done', ['conversation_id' => $conversation_id, 'tokens' => $used]);
}

function wptuts_ai_store_message( $conversation_id, $user_id, $role, $content, $tokens = 0 ) {
    global $wpdb;
    $wpdb->insert($wpdb->prefix . 'wptuts_ai_messages', [
        'conversation_id' => $conversation_id,
        'user_id'         => $user_id,
        'role'            => $role,
        'content'         => $content,
        'token_count'     => $tokens,
        'created_at'      => gmdate('Y-m-d H:i:s'),
    ], ['%s', '%d', '%s', '%s', '%d', '%s']);
}

function wptuts_ai_get_history( $conversation_id, $user_id, $limit = 10 ) {
    global $wpdb;
    $rows = $wpdb->get_results($wpdb->prepare(
        'SELECT role, content FROM ' . $wpdb->prefix . 'wptuts_ai_messages
         WHERE conversation_id = %s AND user_id = %d
         ORDER BY id DESC LIMIT %d',
        $conversation_id, $user_id, $limit
    ));
    $rows = array_reverse($rows);
    return array_map(function ( $row ) {
        return ['role' => $row->role, 'content' => $row->content];
    }, $rows);
}

function wptuts_ai_adjust_tokens( $user_id, $ip_hash, $reserved, $actual ) {
    global $wpdb;
    $table  = $wpdb->prefix . 'wptuts_ai_usage';
    $window = gmdate('Y-m-d 00:00:00');
    $delta  = (int) $actual - (int) $reserved;
    if ( 0 === $delta ) {
        return;
    }
    foreach ( ['user' => (string) $user_id, 'ip' => $ip_hash] as $scope => $key ) {
        $wpdb->query($wpdb->prepare(
            'UPDATE ' . $table . ' SET tokens = GREATEST(0, tokens + %d)
             WHERE scope = %s AND scope_key = %s AND window_start = %s',
            $delta, $scope, $key, $window
        ));
    }
}

The assistant text is sanitised with sanitize_textarea_field() before storage. That preserves line breaks but strips tags. If you later render Markdown to HTML, run the final HTML through wp_kses_post() with a strict allowlist. Do not stream raw HTML to the browser and do not assign model output to innerHTML.

Step 4: Read SSE in the browser without innerHTML

Localise the endpoint and nonce with wp_localize_script(). The client below uses fetch(), a ReadableStream reader and TextDecoder. It splits the buffer on a blank line, parses the SSE fields, and appends text with textContent. That is the key defence: the browser treats the model output as text, not markup.

add_action('wp_enqueue_scripts', function () {
    wp_enqueue_script('wptuts-ai-chat', plugins_url('chat.js', __FILE__), [], '1.0', true);
    wp_localize_script('wptuts-ai-chat', 'wptutsAi', [
        'endpoint' => rest_url('wptuts-ai/v1/chat'),
        'nonce'    => wp_create_nonce('wp_rest'),
    ]);
});

const input = document.getElementById('wptuts-ai-input');
const button = document.getElementById('wptuts-ai-send');
const output = document.getElementById('wptuts-ai-output');
const newline = String.fromCharCode(10);
let conversationId = '';

button.addEventListener('click', async () => {
    const message = input.value.trim();
    if (!message) return;
    output.textContent = '';
    button.disabled = true;

    try {
        const response = await fetch(wptutsAi.endpoint, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'X-WP-Nonce': wptutsAi.nonce,
            },
            body: JSON.stringify({ message, conversation_id: conversationId }),
        });

        if (!response.ok || !response.body) {
            throw new Error('HTTP ' + response.status);
        }

        const reader = response.body.getReader();
        const decoder = new TextDecoder();
        let buffer = '';

        while (true) {
            const { value, done } = await reader.read();
            if (done) break;
            buffer += decoder.decode(value, { stream: true });
            const parts = buffer.split(newline + newline);
            buffer = parts.pop();

            for (const part of parts) {
                const lines = part.split(newline);
                let event = 'message';
                let data = '';
                for (const line of lines) {
                    if (line.startsWith('event: ')) event = line.slice(7);
                    if (line.startsWith('data: ')) data += line.slice(6);
                }
                if (!data) continue;
                const payload = JSON.parse(data);
                if (event === 'meta') conversationId = payload.conversation_id;
                if (event === 'delta') output.textContent += payload.text;
                if (event === 'error') output.textContent += newline + payload.message;
            }
        }
    } catch (error) {
        output.textContent += newline + 'Request failed. Please try again.';
    } finally {
        button.disabled = false;
    }
});

The client keeps the conversation ID in memory. For a real interface, store it in a hidden field or in sessionStorage and add a reset button. If you need to cancel a stream, create an AbortController and call abort() on the fetch signal. The server should also check connection_aborted() inside the cURL write callback if you want to stop upstream work early.

Step 5: Add the kill switch and secrets

Put the API key and the kill switch in wp-config.php, above the wp-settings.php include. The plugin checks the constant at load time and again in the permission callback. That gives you two layers: the plugin does not register the route when disabled, and any already-registered route still rejects requests.

define('WPTUTS_OPENAI_API_KEY', 'sk-your-key');
define('WPTUTS_AI_CHAT_DISABLED', true);

Rotate the key if it is ever committed. Better still, read the key from an environment variable and define the constant from that value. The kill switch is deliberately simple: set it to true, save, and the chat stops. Remove it or set it to false to re-enable.

Troubleshooting

Everything arrives at once. Check gzip, mod_deflate, PHP output_buffering, FastCGI buffering and any CDN. The response must not be buffered. Test with curl -N against the endpoint.
403 invalid nonce. The nonce is tied to the user session and expires. Refresh the page. Confirm the X-WP-Nonce header is present and the action is wp_rest.
401 login required. The route intentionally requires a logged-in user. If you need anonymous chat, add a separate route with stricter IP limits and a different nonce strategy.
429 quota exceeded. Inspect the usage table for the current UTC window. Delete the test row only on a staging site. In production, raise limits or add a paid tier.
Tables missing. Activation hooks run on activation, not on every request. Deactivate and reactivate the plugin, or run the install function from WP-CLI.
cURL errors. Confirm php-curl is enabled and outbound HTTPS is allowed. Some hosts block api.openai.com.
IP limits are wrong behind a proxy. Do not trust X-Forwarded-For blindly. Configure your proxy to set a trusted header and read only that header after validating the proxy IP.

Next steps

Add a conversation list endpoint with an ownership check before returning rows. Add a delete endpoint that removes messages by conversation_id and user_id. Add moderation before storage if the assistant is public. Move quota counters to Redis if you expect bursts. Add an AbortController and a stop button. Finally, wrap the UI in a block pattern or shortcode so editors can place it without touching theme templates.

The important architectural point is that streaming is a transport detail. Authorisation, quota enforcement, sanitisation and storage are the parts that keep the feature safe on a real site.

Originally published on WP Tuts Hub.

AI Content Provenance for WordPress: Log Model, Prompt Hash and Token Usage per Post with a Review Diff

Md. Zubaer Ahammed — Wed, 11 Nov 2026 02:04:37 +0000

A disclaimer under the article is not provenance. Provenance is a record you can query six months later: which model produced this paragraph, which prompt produced that model output, how many tokens it cost, and which human signed it off. If your editorial policy, a client contract or a regulator ever asks "was this written by a machine, and who checked it?", a footnote will not save you — a meta row will.

This tutorial stores a structured provenance record on every AI-assisted post, hashes the prompt instead of storing it, and adds a reviewer-facing diff that compares the human baseline against the current content. The diff is gated by edit_post and a nonce, and it is rendered server-side with WordPress's own wp_text_diff() — no hand-rolled HTML injection.

Why a hash and not the prompt itself

Prompts leak. They contain client names, unpublished product details, internal URLs and occasionally a pasted paragraph of someone else's copyrighted text. Storing the raw prompt in post meta means it lands in every database backup, every staging clone and every support export.

A keyed hash gives you the useful part — was this the same prompt we used on the other twelve posts? — without the liability. Use hash_hmac() with wp_salt() rather than a bare hash(), so an attacker who guesses your prompt cannot confirm it by hashing the guess themselves. The trade-off is real: rotate the salt and every stored hash becomes unverifiable. Document that in your runbook.

Prerequisites

WordPress 6.5 or later (block bindings, wp_date(), typed meta).
PHP 8.0+ with the hash extension (bundled by default).
A child theme or small site plugin — this code belongs in a plugin, not functions.php, because you want it active when the theme is switched.
Your AI generation pipeline must be able to call a PHP function after it writes content. If generation happens outside WordPress, expose a signed REST route or a WP-CLI command that calls the same recorder.
WP-CLI access for the backfill step.

Step 1: Register two meta keys

You need two records, not one. _wpth_ai_provenance holds the current run's metadata. _wpth_ai_baseline holds a snapshot of the content before the first AI run, which is what the diff compares against. The leading underscore marks both as protected meta, so they never appear in the Custom Fields panel where an editor could break them.

add_action( 'init', 'wpth_register_provenance_meta' );

function wpth_register_provenance_meta() {
    $guard = static function ( $allowed, $meta_key, $post_id ) {
        return current_user_can( 'edit_post', $post_id );
    };

    register_post_meta(
        'post',
        '_wpth_ai_provenance',
        array(
            'type'              => 'object',
            'single'            => true,
            'show_in_rest'      => false,
            'sanitize_callback' => 'wpth_sanitize_provenance',
            'auth_callback'     => $guard,
        )
    );

    register_post_meta(
        'post',
        '_wpth_ai_baseline',
        array(
            'type'          => 'string',
            'single'        => true,
            'show_in_rest'  => false,
            'auth_callback' => $guard,
        )
    );
}

Why show_in_rest is false: the record is for auditors, not for the block editor or a headless front end. Keeping it out of REST removes an entire class of exposure. If you later need it over REST, register a dedicated read-only route with its own capability check rather than flipping this flag.

Why auth_callback matters: it is not decoration. WordPress maps it into the edit_post_meta capability check, so even a direct update_post_meta() call from a rogue plugin is filtered through edit_post on that specific post.

The sanitiser

Never trust the array shape coming out of your pipeline. Cast every field, reject anything that is not a 64-character lowercase hex hash, and drop unknown keys entirely.

function wpth_sanitize_provenance( $value ) {
    if ( ! is_array( $value ) ) {
        return array();
    }

    $clean = array(
        'provider'     => sanitize_key( $value['provider'] ?? '' ),
        'model'        => sanitize_text_field( $value['model'] ?? '' ),
        'prompt_hash'  => '',
        'prompt_chars' => absint( $value['prompt_chars'] ?? 0 ),
        'tokens_in'    => absint( $value['tokens_in'] ?? 0 ),
        'tokens_out'   => absint( $value['tokens_out'] ?? 0 ),
        'generated_at' => absint( $value['generated_at'] ?? 0 ),
        'editor_id'    => absint( $value['editor_id'] ?? 0 ),
        'reviewed_by'  => absint( $value['reviewed_by'] ?? 0 ),
        'run_id'       => sanitize_text_field( $value['run_id'] ?? '' ),
    );

    $hash = strtolower( (string) ( $value['prompt_hash'] ?? '' ) );

    if ( preg_match( '/^[a-f0-9]{64}$/', $hash ) ) {
        $clean['prompt_hash'] = $hash;
    }

    return $clean;
}

Step 2: Hash the prompt deterministically

Normalise whitespace before hashing. Otherwise a prompt that differs only by a trailing newline produces a different hash and your "have we run this before?" query returns false negatives forever.

function wpth_hash_prompt( string $prompt, string $provider, string $model ): string {
    $normalised = trim( preg_replace( '/\s+/u', ' ', $prompt ) );
    $material   = $provider . '|' . $model . '|' . $normalised;

    return hash_hmac( 'sha256', $material, wp_salt( 'auth' ) );
}

Including the provider and model in the material means the same prompt sent to two different models yields two different hashes — which is what you want, because the output will differ too.

Step 3: Write the record from the pipeline

Call this from the code that actually writes the generated content. Do not hook it to save_post: that fires on autosaves, revisions, bulk edits and REST saves, and you will end up with provenance records for posts no model ever touched.

function wpth_record_ai_provenance( int $post_id, array $run ): bool {
    $post = get_post( $post_id );

    if ( ! $post || 'post' !== $post->post_type ) {
        return false;
    }

    $existing = get_post_meta( $post_id, '_wpth_ai_provenance', true );

    // Snapshot the human-written content once, before the first AI run.
    if ( empty( $existing ) ) {
        update_post_meta( $post_id, '_wpth_ai_baseline', wp_slash( $post->post_content ) );
        update_post_meta( $post_id, '_wpth_ai_baseline_at', time() );
    }

    $record = wpth_sanitize_provenance(
        array(
            'provider'     => $run['provider'],
            'model'        => $run['model'],
            'prompt_hash'  => wpth_hash_prompt( $run['prompt'], $run['provider'], $run['model'] ),
            'prompt_chars' => mb_strlen( $run['prompt'] ),
            'tokens_in'    => $run['tokens_in'],
            'tokens_out'   => $run['tokens_out'],
            'generated_at' => time(),
            'editor_id'    => get_current_user_id(),
            'run_id'       => $run['run_id'] ?? wp_generate_uuid4(),
        )
    );

    update_post_meta( $post_id, '_wpth_ai_provenance', $record );

    return true;
}

wp_slash() on the baseline is not optional. update_post_meta() expects slashed data, and post content routinely contains backslashes and quotes that will be silently mangled without it.

Step 4: Build the review metabox

The metabox shows the metadata and a button that submits to admin-post.php. It does not render the diff itself — that happens in a POST handler where the nonce can actually be verified.

add_action( 'add_meta_boxes_post', function () {
    add_meta_box(
        'wpth-ai-provenance',
        __( 'AI provenance', 'wpth' ),
        'wpth_render_provenance_box',
        'post',
        'side',
        'high'
    );
} );

function wpth_render_provenance_box( WP_Post $post ) {
    if ( ! current_user_can( 'edit_post', $post->ID ) ) {
        return;
    }

    $record = get_post_meta( $post->ID, '_wpth_ai_provenance', true );

    if ( empty( $record['model'] ) ) {
        echo '<p>' . esc_html__( 'No AI generation recorded for this post.', 'wpth' ) . '</p>';
        return;
    }

    $rows = array(
        __( 'Provider', 'wpth' )    => $record['provider'],
        __( 'Model', 'wpth' )       => $record['model'],
        __( 'Generated', 'wpth' )   => wp_date( 'Y-m-d H:i', $record['generated_at'] ),
        __( 'Prompt hash', 'wpth' ) => substr( $record['prompt_hash'], 0, 16 ) . '…',
        __( 'Tokens', 'wpth' )      => sprintf(
            '%s in / %s out',
            number_format_i18n( $record['tokens_in'] ),
            number_format_i18n( $record['tokens_out'] )
        ),
        __( 'Run by', 'wpth' )      => get_the_author_meta( 'display_name', $record['editor_id'] ),
    );

    echo '<table class="widefat striped"><tbody>';

    foreach ( $rows as $label => $value ) {
        printf(
            '<tr><th scope="row">%s</th><td>%s</td></tr>',
            esc_html( $label ),
            esc_html( (string) $value )
        );
    }

    echo '</tbody></table>';

    printf(
        '<form method="post" action="%s" style="margin-top:1em;">',
        esc_url( admin_url( 'admin-post.php' ) )
    );
    wp_nonce_field( 'wpth_provenance_diff_' . $post->ID, 'wpth_provenance_nonce' );
    echo '<input type="hidden" name="action" value="wpth_provenance_diff">';
    printf( '<input type="hidden" name="post_id" value="%d">', $post->ID );
    submit_button( __( 'Review diff', 'wpth' ), 'secondary', 'submit', false );
    echo '</form>';
}

Step 5: Serve the diff through a nonce-checked handler

This is the part most tutorials get wrong. They fetch the baseline over REST and inject it with innerHTML, which turns a review tool into a stored XSS vector. Use wp_text_diff() instead: it escapes every line with esc_html() internally and returns a complete table.

add_action( 'admin_post_wpth_provenance_diff', 'wpth_handle_provenance_diff' );

function wpth_handle_provenance_diff() {
    $post_id = isset( $_POST['post_id'] ) ? absint( $_POST['post_id'] ) : 0;

    if ( ! $post_id || ! current_user_can( 'edit_post', $post_id ) ) {
        wp_die(
            esc_html__( 'You are not allowed to review this post.', 'wpth' ),
            '',
            array( 'response' => 403 )
        );
    }

    check_admin_referer( 'wpth_provenance_diff_' . $post_id, 'wpth_provenance_nonce' );

    $baseline = (string) get_post_meta( $post_id, '_wpth_ai_baseline', true );
    $current  = (string) get_post_field( 'post_content', $post_id );
    $record   = (array) get_post_meta( $post_id, '_wpth_ai_provenance', true );

    require_once ABSPATH . 'wp-admin/includes/diff.php';

    $diff = wp_text_diff(
        $baseline,
        $current,
        array(
            'title_left'      => __( 'Before AI', 'wpth' ),
            'title_right'     => __( 'Current', 'wpth' ),
            'show_split_view' => false,
        )
    );

    if ( '' === $diff ) {
        $diff = '<p>' . esc_html__( 'No textual change since the baseline was captured.', 'wpth' ) . '</p>';
    }

    wpth_render_diff_page( $post_id, $record, $diff );
}

Two details worth knowing. First, wp_text_diff() returns an empty string — not null — when the two sides match, so test with '' === $diff. Second, it runs both sides through normalize_whitespace() before splitting on newlines, which means block comment delimiters like  appear as diff lines. That is a feature: a reviewer can see when a block type changed, not just the words.

function wpth_render_diff_page( int $post_id, array $record, string $diff ) {
    echo '<!DOCTYPE html><html ' . get_language_attributes() . '><head>';
    echo '<meta charset="' . esc_attr( get_bloginfo( 'charset' ) ) . '">';
    echo '<title>' . esc_html__( 'AI review diff', 'wpth' ) . '</title>';
    wp_admin_css( 'wp-admin' );
    echo '</head><body class="wp-core-ui"><div class="wrap">';

    printf(
        '<h1>%s</h1>',
        esc_html( sprintf( __( 'AI review diff: %s', 'wpth' ), get_the_title( $post_id ) ) )
    );

    printf(
        '<p>%s</p>',
        esc_html(
            sprintf(
                /* translators: 1: model, 2: provider, 3: date */
                __( 'Model %1$s from %2$s, generated %3$s.', 'wpth' ),
                $record['model'],
                $record['provider'],
                wp_date( 'Y-m-d H:i', (int) $record['generated_at'] )
            )
        )
    );

    // $diff comes from wp_text_diff(): already escaped and wrapped in a table.
    echo $diff;

    printf(
        '<p><a href="%s">%s</a></p>',
        esc_url( get_edit_post_link( $post_id ) ),
        esc_html__( 'Back to the editor', 'wpth' )
    );

    echo '</div></body></html>';
    exit;
}

Step 6: Surface token spend in the posts list

Provenance you never look at is dead weight. A column in the posts list makes model and token cost visible at a glance, which is usually enough to spot a runaway prompt before the invoice arrives.

add_filter( 'manage_post_posts_columns', function ( $columns ) {
    $columns['wpth_ai'] = __( 'AI', 'wpth' );
    return $columns;
} );

add_action( 'manage_post_posts_custom_column', function ( $column, $post_id ) {
    if ( 'wpth_ai' !== $column ) {
        return;
    }

    $record = get_post_meta( $post_id, '_wpth_ai_provenance', true );

    if ( empty( $record['model'] ) ) {
        echo '&mdash;';
        return;
    }

    $total = (int) $record['tokens_in'] + (int) $record['tokens_out'];

    printf(
        '<span title="%s">%s &middot; %s</span>',
        esc_attr(
            sprintf(
                /* translators: 1: prompt hash, 2: input tokens, 3: output tokens */
                __( 'Prompt hash %1$s, %2$d in / %3$d out', 'wpth' ),
                $record['prompt_hash'],
                $record['tokens_in'],
                $record['tokens_out']
            )
        ),
        esc_html( $record['model'] ),
        esc_html( number_format_i18n( $total ) )
    );
}, 10, 2 );

Step 7: Publish a disclosure with block bindings

Readers deserve the same transparency your auditors get. Block bindings (WordPress 6.5+) let a paragraph pull its text from post meta, so the disclosure stays in sync without anyone editing the post again.

add_action( 'init', function () {
    register_block_bindings_source(
        'wpth/provenance',
        array(
            'label'              => __( 'AI provenance', 'wpth' ),
            'uses_context'       => array( 'postId' ),
            'get_value_callback' => static function ( array $args, WP_Block $block ) {
                $post_id = isset( $block->context['postId'] )
                    ? (int) $block->context['postId']
                    : (int) get_the_ID();

                $record = get_post_meta( $post_id, '_wpth_ai_provenance', true );

                if ( empty( $record['model'] ) ) {
                    return '';
                }

                return sprintf(
                    /* translators: 1: model name, 2: date */
                    __( 'AI-assisted draft produced with %1$s and reviewed on %2$s.', 'wpth' ),
                    $record['model'],
                    wp_date( get_option( 'date_format' ), (int) $record['generated_at'] )
                );
            },
        )
    );
} );

In the editor, add a Paragraph block, open the block toolbar's binding panel, and pick AI provenance. The block renders the returned string and escapes it for you — do not return HTML from the callback.

Backfilling posts that predate the code

Any post already AI-assisted before you shipped this has no baseline, so its diff will be empty. Capture one from the current content and accept that the first diff is a no-op — from then on, changes are tracked.

wp eval '
$ids = get_posts( array(
    "post_type"      => "post",
    "post_status"    => "any",
    "posts_per_page" => -1,
    "fields"         => "ids",
    "meta_key"       => "_wpth_ai_provenance",
) );

foreach ( $ids as $id ) {
    if ( get_post_meta( $id, "_wpth_ai_baseline", true ) ) {
        continue;
    }

    update_post_meta( $id, "_wpth_ai_baseline", wp_slash( get_post_field( "post_content", $id ) ) );
    WP_CLI::log( "Baseline captured for post {$id}" );
}
'

Troubleshooting

The diff page returns "Are you sure you want to do this?" — the nonce expired. Nonces live 12–24 hours, so a tab left open overnight fails. Reload the editor and press the button again.
Metadata saves but the metabox shows nothing — your sanitiser is dropping the array. Log the return value of wpth_sanitize_provenance(); the usual culprit is a hash that is not exactly 64 lowercase hex characters, or a provider string that sanitize_key() reduces to an empty string.
Baseline contains escaped quotes — you skipped wp_slash() on write, or applied wp_unslash() twice on read. Read with get_post_meta() and do not unslash again.
Every hash changed after a migration — wp_salt() is derived from AUTH_KEY and friends. If those constants differ between environments, hashes are not comparable across them. Store the salt fingerprint alongside the record if cross-environment comparison matters.
Token totals look doubled — you are recording both the generation run and a follow-up rewrite into the same single meta key. Either keep a history array or accept that the record reflects the latest run only, and say so in your policy.
Diff shows the whole post as changed — the baseline was captured after the AI write, not before. Check the order of operations in wpth_record_ai_provenance().

Next steps

Add a reviewed_by and reviewed_at pair written from a second metabox button, so sign-off is a separate, timestamped event from generation.
Store the WordPress revision ID that the AI run produced, then link the diff screen to revision.php for a native side-by-side.
Query the meta with WP_Query and a meta_key to build a monthly token-spend report per model — useful when you are deciding whether to downgrade a model for short posts.
Export the whole provenance table as JSON for a client audit, using a capability-gated admin_post handler that streams a file rather than printing to the page.
If you accept content from outside contributors, pair this with a REST route that requires an application password and writes provenance on their behalf.

Originally published on WP Tuts Hub.

No Shipping Options Available in WooCommerce: Fix It

Md. Zubaer Ahammed — Wed, 11 Nov 2026 02:00:32 +0000

When the checkout blocks the order with “There are no shipping options available”, WooCommerce has already built the cart, priced the items and asked every shipping method for a rate — and received nothing back. The WooCommerce no shipping options error is almost never a bug in the plugin itself. It is the predictable result of a zone that did not match the customer's address, a method instance that was not available, or a rule that excluded every item in the package. This tutorial compares three ways to chase it down and then builds the one that gives a definitive answer instead of a guess.

You need WooCommerce 8.x or later, an admin account with the manage_woocommerce capability, and file access (SFTP, a file manager, or WP-CLI) to drop a small must-use plugin into wp-content/mu-plugins/. No live site changes are needed until you have read the diagnostic output.

What the “no shipping options available” message actually means in the shipping pipeline

Shipping in WooCommerce runs in four stages, and the error appears only at the end of them:

Packages. WC_Cart::get_shipping_packages() splits the cart into one or more packages, each with a destination array (country, state, postcode, city) and a contents array.
Zone matching. WC_Shipping_Zones::get_zone_matching_package() walks the zones in their saved order and returns the first zone whose location rules match the destination. Matching stops there — it does not fall through to the next zone if that zone has no usable methods.
Method availability. Every enabled method instance in the matched zone is asked is_available( $package ). Flat Rate checks its own class costs, Free Shipping checks its minimum amount or coupon requirement, and live-rate gateways check their API credentials.
Rates. Available methods return WC_Shipping_Rate objects. If the final array is empty, the Checkout block renders the message you are staring at.

That order matters, because it tells you where to look. A zone that matches but yields no rates looks identical to a zone that never matched — from the customer's side, both produce the same sentence.

Three ways to find the cause, and when each one is the right tool

Auditing zones and method instances in the admin

Open WooCommerce → Settings → Shipping and read every zone, its regions, and the methods inside it. This is fast, needs no code, and is the correct first move on a store with one or two zones, no shipping classes and no live-rate extensions. It is also blind: it cannot tell you which zone a specific postcode matched, and it cannot see rules added by a plugin or a snippet.

Dumping matched zones and packages from a live cart

Add a small diagnostic that rebuilds the packages for the current cart and prints the matched zone, the methods inside it, their availability and the resulting rates. This takes ten minutes to set up and answers the question directly, including for carts with classes, weight rules and third-party methods. On any store with more than one zone, this is the approach worth implementing — and it is the one built in full below.

Forcing a fallback rate with a filter

Hooking woocommerce_package_rates and injecting a rate when the array is empty guarantees the customer can always pay. It is a legitimate business rule for “we will quote delivery after the order”, but it is not a diagnosis. Used as a first response it hides the real fault, and you will keep shipping free or under-priced orders for months. Keep it for last, and only when the fallback is a deliberate policy.

Zone coverage fails silently when no region matches the customer address

Zones are evaluated top to bottom, and the first match wins. Three coverage mistakes account for most cases:

No catch-all zone. If every zone lists specific countries and the customer is in a country that appears nowhere, no zone matches at all. Add a “Rest of the world” zone with a Zone region of Everywhere and give it at least one method.
A matching zone with no methods. The customer's country is listed in a zone that contains only a disabled method. Matching stops there, so the perfectly good zone below it is never consulted.
Over-specific rules. Postcode rules such as SW* or ranges like 90210...90220 only match when the postcode is present and formatted as expected. A zone that requires a postcode will not match a cart where only the country is known.

Also check WooCommerce → Settings → Shipping → Shipping options. If “Hide shipping costs until an address is entered” is on and the customer has not supplied a full address, the cart has nothing to price against — the Blocks checkout often surfaces that as the same error rather than a prompt.

To list every zone, its regions and its methods without clicking through the admin, use WP-CLI:

wp eval '
foreach ( WC_Shipping_Zones::get_zones() as $data ) {
    $zone = WC_Shipping_Zones::get_zone( $data["zone_id"] );
    printf( "#%d %s\n", $zone->get_id(), $zone->get_zone_name() );
    foreach ( $zone->get_zone_locations() as $loc ) {
        printf( "   location: %s = %s\n", $loc->type, $loc->code );
    }
    foreach ( $zone->get_shipping_methods( true ) as $method ) {
        printf( "   method: %s (%s) enabled=%s\n", $method->get_title(), $method->id, $method->is_enabled() ? "yes" : "no" );
    }
}
'

Reading the output in zone order shows you immediately whether a country is covered twice, covered by an empty zone, or not covered at all.

A method instance can be enabled and still return nothing

Inside a zone, each row is a separate instance with its own settings. The checkbox on the left only controls whether the instance is active; availability is decided by the instance's own rules:

Free Shipping with “Requires a minimum order amount” or “Requires a coupon” returns nothing when the cart does not qualify. If it is the only method in the zone, the checkout breaks.
Flat Rate with a blank cost for the product's shipping class and a blank “No shipping class cost” produces a zero-cost rate — still a rate, so no error, but a silent revenue leak worth spotting while you are in there.
Live rates (carrier extensions, table-rate plugins) return nothing when the API rejects the request: missing weight, missing dimensions, an unserviceable postcode, or expired credentials. Check WooCommerce → Status → Logs for the extension's own log before touching zones.

One more trap: rates are cached in the customer session under shipping_for_package_<key>. After you change a zone or a method, an existing session can keep serving the old, empty result. Empty the cart, or clear the session key, before you conclude the fix did not work.

Shipping classes and weight rules exclude whole carts without an error

Shipping classes are assigned per product and per variation, and a single mismatched item can change the outcome for the whole package. Two things to verify:

Every product in the cart has a class that the matched method actually prices. A class created after the method was configured will have no cost row.
Weight-based rules use the summed weight of the package, not the per-item weight. A table-rate rule of “0–1 kg” fails for a cart of three 0.4 kg items even though each item looks fine on its own product page.

This is exactly the class of problem the admin UI cannot show you, which is why the next step is a dump rather than more clicking.

Build the diagnostic dump that shows the matched zone, methods and rates

Create wp-content/mu-plugins/shipping-match-debugger.php. A must-use plugin loads automatically, cannot be deactivated by accident, and stays out of the plugins list. It only runs for logged-in users who can manage WooCommerce and who append ?ship_debug=1 to the cart URL, so customers never see the output.

<?php
/**
 * Plugin Name: WPTH Shipping Match Debugger
 * Description: Prints packages, matched zones, methods and rates for the current cart.
 */

defined( 'ABSPATH' ) || exit;

add_action( 'woocommerce_before_cart', 'wpth_dump_shipping_matches' );

function wpth_dump_shipping_matches() {
    if ( ! isset( $_GET['ship_debug'] ) || ! current_user_can( 'manage_woocommerce' ) ) {
        return;
    }

    if ( ! WC()->cart || WC()->cart->is_empty() ) {
        return;
    }

    WC()->cart->calculate_shipping();
    $packages = WC()->shipping()->get_packages();

    echo '<pre style="padding:1em;background:#111;color:#0f0;font-size:13px;white-space:pre-wrap">';

    foreach ( $packages as $index => $package ) {
        printf(
            "Package %d: %d item(s) to %s / %s / %s\n",
            $index,
            count( $package['contents'] ),
            $package['destination']['country'],
            $package['destination']['state'],
            $package['destination']['postcode']
        );

        $zone = WC_Shipping_Zones::get_zone_matching_package( $package );
        printf( "  Zone: #%d %s\n", $zone->get_id(), $zone->get_zone_name() );

        foreach ( $zone->get_shipping_methods( true ) as $method ) {
            printf(
                "  Method: %s [%s:%d] available=%s\n",
                $method->get_title(),
                $method->id,
                $method->instance_id,
                $method->is_available( $package ) ? 'yes' : 'no'
            );
        }

        if ( empty( $package['rates'] ) ) {
            echo "  RATES: none - this package is what breaks the checkout\n";
        } else {
            foreach ( $package['rates'] as $rate ) {
                printf( "  Rate: %s = %s\n", $rate->get_label(), $rate->get_cost() );
            }
        }

        foreach ( $package['contents'] as $item ) {
            printf(
                "  Item: %s x%d | class=%s | weight=%s\n",
                $item['data']->get_name(),
                $item['quantity'],
                $item['data']->get_shipping_class() ?: 'none',
                wc_format_weight( $item['data']->get_weight() )
            );
        }
    }

    echo '</pre>';
}

Add the products to the cart as the customer would, then load /cart/?ship_debug=1 while logged in as an administrator. The block prints one section per package.

Here is the output on a test store running WooCommerce 11.2.2, with a single shipping zone for the United Kingdom (Flat rate £4.95, plus £20 for the Bulky shipping class). The cart holds two mugs and a bench. With a US shipping address, no zone matches, so there is nothing to price:

Package 0: 2 item(s) to US / CA / 94105
  Zone: #0 Locations not covered by your other zones
  RATES: none - this package is what breaks the checkout
  Item: Enamel Mug x2 | class=none | weight=0.4 kg
  Item: Garden Bench x1 | class=bulky | weight=18 kg

The same cart with a UK address matches the zone, the method is available, and the rate includes the Bulky class cost:

Package 0: 2 item(s) to GB /  / SW1A 1AA
  Zone: #1 United Kingdom
  Method: Flat rate [flat_rate:1] available=yes
  Rate: Flat rate = 24.95
  Item: Enamel Mug x2 | class=none | weight=0.4 kg
  Item: Garden Bench x1 | class=bulky | weight=18 kg

Reading the dump: the four lines that identify the failure

Work down each package in order and stop at the first line that looks wrong:

Destination. If the country, state or postcode is empty or wrong, the problem is upstream of shipping — an address field, a default customer location setting, or a geolocation plugin.
Zone. A zone ID of 0 named “Locations not covered by your other zones” in the dump (the Shipping zones screen calls the same zone “Rest of the world”) means no configured zone matched and WooCommerce fell back to the default. That is a coverage gap, not a method problem.
Method availability. A method listed with available=no is the culprit: its minimum amount, coupon requirement, class cost or API call rejected the package. A zone with no methods listed at all is the other common culprit.
Rates. If methods show available=yes but the rate list is empty, a filter or a third-party plugin is stripping the rates after calculation — search the codebase for woocommerce_package_rates.

To catch that last case in the log rather than on screen, add a temporary logger. It writes only when WP_DEBUG is on, so it is safe to leave in a staging copy:

add_filter( 'woocommerce_package_rates', function ( $rates, $package ) {
    if ( ! empty( $rates ) || ! defined( 'WP_DEBUG' ) || ! WP_DEBUG ) {
        return $rates;
    }

    $weight = 0;
    foreach ( $package['contents'] as $item ) {
        $weight += (float) $item['data']->get_weight() * $item['quantity'];
    }

    error_log( sprintf(
        '[shipping] no rates for %s/%s/%s | items=%d | weight=%s',
        $package['destination']['country'],
        $package['destination']['state'],
        $package['destination']['postcode'],
        count( $package['contents'] ),
        wc_format_weight( $weight )
    ) );

    return $rates;
}, 10, 2 );

Fix the cause in the zone, not in the checkout template

Once the dump names the failing stage, the repair is usually a two-minute admin change:

No zone matched: add a catch-all zone with the Everywhere region and at least one method, then drag it to the bottom of the zone list.
Wrong zone matched: reorder the zones so the more specific one sits above the general one, and remove the country from the zone that should not have claimed it.
Method unavailable: open the instance and relax the condition — lower the free-shipping threshold, remove the coupon requirement, or fill in the missing class cost.
Live rates empty: fix the data the carrier needs (weight, dimensions, a valid postcode) or the credentials, and check the extension log again.

After any change, empty the cart and re-run the dump. If the rates appear but the checkout still complains, clear the shipping transient version with WC_Cache_Helper::get_transient_version( 'shipping', true ) and retest in a private window.

When a fallback rate filter is the correct answer

Some stores genuinely cannot price every destination — freight to remote islands, made-to-order items, or a trade catalogue quoted after the order. In that case, and only after the dump has confirmed the gap is intentional, inject a zero-cost “arranged later” rate so the order can complete:

add_filter( 'woocommerce_package_rates', function ( $rates, $package ) {
    if ( ! empty( $rates ) ) {
        return $rates;
    }

    $fallback = new WC_Shipping_Rate(
        'wpth_fallback',
        __( 'Delivery arranged after order', 'your-textdomain' ),
        0,
        array(),
        'wpth_fallback',
        0
    );

    return array( 'wpth_fallback' => $fallback );
}, 20, 2 );

Pair it with an order note or an admin email so the quote is never forgotten, and log every time it fires — a fallback that triggers on 30% of orders is a coverage problem wearing a disguise.

The natural follow-up is to stop discovering these gaps one customer at a time: wrap the same package-building logic in a WP-CLI command that takes a CSV of country/state/postcode combinations, replays each one through WC_Shipping_Zones::get_zone_matching_package(), and prints the zone and rate count. Run it after every zone change and you will see a newly orphaned region before a customer does.

Originally published on WP Tuts Hub.