WordPress Tagged Revalidation

<?php
/**
 * Plugin Name: Tagged Revalidate
 * Description: Notifies the front end to purge its cache tag for a single
 *              content object whenever that object changes, instead of
 *              relying on time-based revalidation.
 * Author: Alexander Talaat
 */

if (!defined('ABSPATH')) {
    exit;
}

// Set in wp-config.php:
//   define('REVALIDATE_ENDPOINT', 'https://example.com/api/revalidate');
//   define('REVALIDATE_SECRET', getenv('REVALIDATE_SECRET'));

/**
 * Sign and send one tag invalidation. Fire-and-forget on purpose — an
 * editor's save should never block on the front end's cache layer.
 */
function tr_send_revalidation(string $tag): void
{
    if (!defined('REVALIDATE_SECRET') || REVALIDATE_SECRET === '' || !defined('REVALIDATE_ENDPOINT')) {
        error_log('[tagged-revalidate] REVALIDATE_SECRET or REVALIDATE_ENDPOINT is not set — skipping.');
        return;
    }

    $timestamp = (string) time();
    $payload   = wp_json_encode(['tag' => $tag]);
    $signature = hash_hmac('sha256', $timestamp . '.' . $payload, REVALIDATE_SECRET);

    wp_remote_post(REVALIDATE_ENDPOINT, [
        'timeout'  => 5,
        'blocking' => false,
        'headers'  => [
            'Content-Type'            => 'application/json',
            'X-Revalidate-Timestamp'  => $timestamp,
            'X-Revalidate-Signature'  => $signature,
        ],
        'body' => $payload,
    ]);
}

/** Skip revisions, autosaves, and anything not actually published. */
function tr_tag_for_post(int $post_id): ?string
{
    $post = get_post($post_id);
    if (!$post || $post->post_status !== 'publish') {
        return null;
    }
    if (wp_is_post_revision($post_id) || wp_is_post_autosave($post_id)) {
        return null;
    }
    return $post->post_type . ':' . $post_id;
}

add_action('save_post', function (int $post_id): void {
    $tag = tr_tag_for_post($post_id);
    if ($tag !== null) {
        tr_send_revalidation($tag);
    }
});

add_action('deleted_post', function (int $post_id, WP_Post $post): void {
    tr_send_revalidation($post->post_type . ':' . $post_id);
}, 10, 2);

foreach (['created_term', 'edited_term', 'delete_term'] as $hook) {
    add_action($hook, function (int $term_id, int $tt_id, string $taxonomy): void {
        tr_send_revalidation($taxonomy . ':' . $term_id);
    }, 10, 3);
}

import { createHmac, timingSafeEqual } from 'node:crypto';
import { revalidateTag } from 'next/cache';

const SECRET = process.env.REVALIDATE_SECRET;
const MAX_SKEW_SECONDS = 60;

interface RevalidatePayload {
  tag: string;
}

export async function POST(request: Request): Promise<Response> {
  if (!SECRET) {
    // Fail closed: an unconfigured secret must never be treated as "no
    // verification required."
    return new Response('Revalidation is not configured', { status: 500 });
  }

  const signature = request.headers.get('x-revalidate-signature');
  const timestamp = request.headers.get('x-revalidate-timestamp');
  if (!signature || !timestamp) {
    return new Response('Missing signature', { status: 401 });
  }

  // Reject stale (or replayed) requests before doing anything else — this
  // is what turns a captured signature into a request usable for about a
  // minute instead of a request usable forever.
  const requestTime = Number(timestamp);
  const skew = Math.abs(Date.now() / 1000 - requestTime);
  if (!Number.isFinite(requestTime) || skew > MAX_SKEW_SECONDS) {
    return new Response('Stale request', { status: 401 });
  }

  const body = await request.text();

  const expected = createHmac('sha256', SECRET).update(`${timestamp}.${body}`).digest();
  let provided: Buffer;
  try {
    provided = Buffer.from(signature, 'hex');
  } catch {
    return new Response('Malformed signature', { status: 401 });
  }

  // timingSafeEqual throws on a length mismatch rather than returning
  // false, and a naive `===` on hex strings leaks timing information
  // proportional to how many leading characters match — enough for an
  // attacker to recover a valid signature byte by byte over many requests.
  // Check length first (safe to do in variable time; length isn't secret),
  // then compare in constant time.
  if (provided.length !== expected.length || !timingSafeEqual(expected, provided)) {
    return new Response('Invalid signature', { status: 401 });
  }

  let payload: RevalidatePayload;
  try {
    payload = JSON.parse(body);
  } catch {
    return new Response('Invalid payload', { status: 400 });
  }

  if (!payload.tag) {
    return new Response('Missing tag', { status: 400 });
  }

  revalidateTag(payload.tag);
  return Response.json({ revalidated: true, tag: payload.tag });
}

/**
 * Typed fetch wrapper for the WordPress REST API that attaches a cache tag
 * per content object, matching the tags the mu-plugin invalidates by.
 * Pass `revalidate: false` for content that's only ever invalidated by tag.
 */
interface WpFetchOptions extends Omit<RequestInit, 'cache'> {
  tags?: string[];
  revalidate?: number | false;
}

const WORDPRESS_API_URL = process.env.WORDPRESS_API_URL;

export async function wpFetch<T>(path: string, options: WpFetchOptions = {}): Promise<T> {
  if (!WORDPRESS_API_URL) {
    throw new Error('WORDPRESS_API_URL is not set');
  }
  const { tags = [], revalidate = 3600, ...init } = options;
  const url = new URL(path, WORDPRESS_API_URL);

  const response = await fetch(url, {
    ...init,
    next: { tags, revalidate }
  });

  if (!response.ok) {
    throw new Error(`WordPress fetch failed: ${response.status} ${response.statusText} — ${url}`);
  }

  return response.json() as Promise<T>;
}

export interface WpPost {
  id: number;
  slug: string;
  title: { rendered: string };
  content: { rendered: string };
  modified: string;
}

/** Tagged `post:<slug>` — invalidated the moment this post is saved or trashed. */
export async function getPostBySlug(slug: string): Promise<WpPost | undefined> {
  const posts = await wpFetch<WpPost[]>(`/wp-json/wp/v2/posts?slug=${encodeURIComponent(slug)}&_embed=1`, {
    tags: [`post:${slug}`]
  });
  return posts[0];
}