Seguridad de rutas, salida y autorización

Las integraciones de caché operan sobre respuestas públicas y artefactos del sistema de archivos. Un pequeño error puede exponer contenido privado, crear un path traversal o eliminar un almacén más amplio de lo previsto. Aplica las salvaguardas de esta guía antes de añadir un hook o de llamar a un helper.

Define el límite de representación

Una clave de caché compartida solo puede representar datos que sean idénticos para cada visitante que pueda recibirlos. No almacenes en caché una salida que varíe según:

• el usuario conectado o su capacidad;
• la autorización, la suscripción o la cuenta;
• el carrito, el checkout, la sesión o la contraseña;
• un nonce, un token CSRF o una URL de un solo uso;
• un parámetro de consulta o un cuerpo de solicitud privados;
• una cookie que no esté incluida en una regla de omisión explícita;
• la geografía, la moneda, el idioma o el dispositivo, salvo que esa variación disponga de una clave independiente segura.

Si una función cambia de pública a privada, impedir escrituras futuras no basta. Desactiva la entrega directa desde el servidor, borra los artefactos de origen existentes, invalida la CDN y verifica todas las sesiones afectadas antes de volver a habilitar la caché.

Usa rutas relativas JSON, no nombres de archivo arbitrarios

pom_cache_json_normalize_relative_path() acepta una ruta relativa restringida .json y devuelve una cadena vacía cuando no es válida. Rechaza rutas absolutas, barras invertidas, bytes nulos, segmentos de recorrido, barras dobles, sufijos .json ausentes y caracteres no admitidos.

Valida antes de cualquier operación:

$relative_path = pom_cache_json_normalize_relative_path(
    'archive/book/page-2.json'
);

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

$json = pom_cache_json_read(
    $relative_path,
    array( 'integration' => 'my_catalog' )
);

No concatenes la entrada de una solicitud en una ruta de caché absoluta. Deja que el helper público aplique el directorio base del sitio actual y las comprobaciones de contención.

Valida antes de purgar

pom_cache_json_purge() elimina un único archivo solo cuando relative_path se normaliza correctamente. Un relative_path ausente o inválido selecciona una purga JSON completa del sitio actual.

Esto hace que la validación previa sea obligatoria cuando el alcance previsto es exacto:

$candidate = isset( $_POST['cache_path'] )
    ? sanitize_text_field( wp_unslash( $_POST['cache_path'] ) )
    : '';

$relative_path = pom_cache_json_normalize_relative_path( $candidate );
if ( '' === $relative_path ) {
    wp_die( esc_html__( 'Invalid cache path.', 'my-plugin' ) );
}

pom_cache_json_purge(
    array(
        'relative_path' => $relative_path,
        'context'       => 'my_plugin_manual_refresh',
    )
);

Para rutas fijas propiedad de la aplicación, prefiere constantes o constructores deterministas antes que aceptar una ruta sin procesar procedente de una solicitud.

Protege los endpoints que cambian estado

Los helpers de POM Cache no autorizan tu controlador. Antes de borrar desde una acción AJAX, REST o de administración:

1. autentica al solicitante;
2. comprueba la capacidad exacta requerida;
3. verifica un nonce o el contrato de autenticación de la ruta REST;
4. sanea y valida toda la entrada;
5. selecciona el helper más específico;
6. devuelve un resultado escapado y no sensible.

No expongas una URL de «borrar caché» sin autenticación.

Respeta el alcance multisitio

Los helpers de alto nivel operan en el contexto del blog actual. Para dirigirte a otro sitio:

$site_id = 12;

switch_to_blog( $site_id );
try {
    if ( function_exists( 'pom_cache_delete_site_cache' ) ) {
        pom_cache_delete_site_cache( 'my_plugin_network_sync' );
    }
    if ( function_exists( 'pom_cache_json_delete_site_cache' ) ) {
        pom_cache_json_delete_site_cache( 'my_plugin_network_sync' );
    }
} finally {
    restore_current_blog();
}

Autoriza la operación de red antes de cambiar de sitio. Nunca recorras en bucle identificadores de blog arbitrarios proporcionados por el usuario.

Mantén las devoluciones de llamada de los filtros conservadoras

Los filtros de elegibilidad normalmente deberían convertir true en false, nunca al revés. Una devolución de llamada que vuelva a habilitar una lectura rechazada puede eludir las salvaguardas de cookie o de DONOTCACHEPAGE de POM Cache.

Los filtros de salida deben devolver una cadena y permanecer deterministas. Nunca inyectes datos por usuario en pom_cache_buffer ni en pom_cache_ob_callback_filter.

Los filtros de rutas son contratos de despliegue. Cambiar un directorio para WordPress mientras Apache, el early drop-in, las estadísticas o la eliminación siguen usando la ruta antigua produce artefactos obsoletos o inaccesibles. Prefiere el ajuste Cache Location salvo que controles todas las capas.

Evita la eliminación de bajo nivel del sistema de archivos

Usa pom_cache_delete_site_cache(), pom_cache_json_delete_site_cache() o un helper JSON exacto. Aplican las rutas del sitio actual, los filtros públicos y las salvaguardas de contención.

No elimines de forma recursiva una raíz de caché calculada, no sigas enlaces simbólicos ni uses un glob sin validar. No expongas rutas absolutas del sistema de archivos en errores públicos ni en informes de soporte.