, content: Content|null, deletion: Deletion|null, read_at: string} */ final class ChangePreview { /** * Post fields shown as current → proposed, by REST name. */ private const POST_FIELDS = array( 'title' => 'post_title', 'status' => 'post_status', 'slug' => 'post_name', 'excerpt' => 'post_excerpt', ); /** * Entity types read as posts. */ private const POST_TYPES = array( 'post', 'page' ); /** * Characters of each body sent for the content diff. Beyond it the body * is cut, and said to be: the queue lists up to 100 holds at once. */ public const CONTENT_MAX = 50000; /** * Constructor. * * @param SnapshotService|null $snapshots For the entity types extensions own. */ public function __construct( private readonly ?SnapshotService $snapshots = null ) { } /** * The preview of one held action, or null when there is none to give. * * @param ActionDescriptor $action The held action, with its stored input. * @param string|null $current_name The target's name now, null when gone. * @return Preview|null */ public function for_action( ActionDescriptor $action, ?string $current_name ): ?array { if ( null !== $this->snapshots?->provider( $action->entity_type ) ) { return null; } if ( 'delete' === $action->action_cat ) { return $this->deletion( $action, $current_name ); } if ( 'update' !== $action->action_cat || 'rest' !== $action->source ) { return null; } $changes = match ( true ) { in_array( $action->entity_type, self::POST_TYPES, true ) => $this->post( $action ), 'option' === $action->entity_type => self::options( $action->input ), 'user' === $action->entity_type => self::user( $action ), default => null, }; // Nothing it can show - only fields it does not preview were sent. if ( null === $changes || ( array() === $changes['fields'] && null === $changes['content'] ) ) { return null; } return self::shaped( $changes['fields'], $changes['content'] ); } /** * A post or page update. * * @param ActionDescriptor $action The action. * @return array{fields: list, content: Content|null}|null */ private function post( ActionDescriptor $action ): ?array { $post = null === $action->entity_id ? null : get_post( $action->entity_id ); if ( ! $post instanceof \WP_Post || ! current_user_can( 'edit_post', $post->ID ) ) { return null; } $labels = array( 'title' => __( 'Title', 'agentic-daisy-ai-agent-firewall' ), 'status' => __( 'Status', 'agentic-daisy-ai-agent-firewall' ), 'slug' => __( 'Slug', 'agentic-daisy-ai-agent-firewall' ), 'excerpt' => __( 'Excerpt', 'agentic-daisy-ai-agent-firewall' ), ); $fields = array(); foreach ( self::POST_FIELDS as $name => $column ) { if ( array_key_exists( $name, $action->input ) ) { $fields[] = self::field( $name, $labels[ $name ], $post->{$column}, self::raw( $action->input[ $name ] ) ); } } return array( 'fields' => $fields, 'content' => array_key_exists( 'content', $action->input ) ? self::content( (string) $post->post_content, self::text( self::raw( $action->input['content'] ) ) ) : null, ); } /** * Both bodies, each cut at CONTENT_MAX characters. * * @param string $current The body now. * @param string $proposed The body the agent sent. * @return Content */ private static function content( string $current, string $proposed ): array { return array( 'current' => mb_substr( $current, 0, self::CONTENT_MAX ), 'proposed' => mb_substr( $proposed, 0, self::CONTENT_MAX ), 'truncated' => mb_strlen( $current ) > self::CONTENT_MAX || mb_strlen( $proposed ) > self::CONTENT_MAX, ); } /** * A settings write: each key that names a setting core's REST API * exposes. Other keys name nothing the firewall reads - the keys are the * agent's, and must never choose an option to read. * * @param array $input The settings sent. * @return array{fields: list, content: null}|null */ private static function options( array $input ): ?array { if ( ! current_user_can( 'manage_options' ) ) { return null; } $settings = self::rest_settings(); $unset = new \stdClass(); $fields = array(); foreach ( $input as $name => $proposed ) { if ( is_string( $name ) && isset( $settings[ $name ] ) ) { $current = get_option( $settings[ $name ], $unset ); $fields[] = self::field( $name, $name, $unset === $current ? null : $current, $proposed ); } } return array( 'fields' => $fields, 'content' => null, ); } /** * Option names by the name core's settings endpoint gives them, as * WP_REST_Settings_Controller works them out. * * @return array */ private static function rest_settings(): array { $names = array(); foreach ( get_registered_settings() as $option => $args ) { $rest = $args['show_in_rest'] ?? false; if ( false === $rest ) { continue; } $name = is_array( $rest ) && isset( $rest['name'] ) ? (string) $rest['name'] : (string) $option; $names[ $name ] = (string) $option; } return $names; } /** * A user update: role and email. * * @param ActionDescriptor $action The action. * @return array{fields: list, content: null}|null */ private static function user( ActionDescriptor $action ): ?array { $user = null === $action->entity_id ? false : get_user_by( 'id', $action->entity_id ); if ( ! $user instanceof \WP_User || ! current_user_can( 'edit_user', $user->ID ) ) { return null; } $fields = array(); if ( array_key_exists( 'roles', $action->input ) ) { $proposed = $action->input['roles']; $fields[] = self::field( 'roles', __( 'Role', 'agentic-daisy-ai-agent-firewall' ), implode( ', ', $user->roles ), is_array( $proposed ) ? implode( ', ', array_map( 'strval', array_filter( $proposed, 'is_scalar' ) ) ) : $proposed ); } if ( array_key_exists( 'email', $action->input ) ) { $fields[] = self::field( 'email', __( 'Email', 'agentic-daisy-ai-agent-firewall' ), $user->user_email, $action->input['email'] ); } return array( 'fields' => $fields, 'content' => null, ); } /** * What a deletion removes, and whether it can come back from the trash. * * @param ActionDescriptor $action The action. * @param string|null $current_name The target's name now. * @return Preview|null */ private function deletion( ActionDescriptor $action, ?string $current_name ): ?array { if ( ! $this->may_read( $action ) ) { return null; } return self::shaped( array(), null, array( 'name' => $current_name, 'permanent' => 'rest' === $action->source ? self::permanent( $action ) : null, ) ); } /** * Whether the person may read the target a deletion names. * * @param ActionDescriptor $action The action. */ private function may_read( ActionDescriptor $action ): bool { $id = $action->entity_id; return match ( $action->entity_type ) { 'post', 'page', 'media' => null !== $id && current_user_can( 'edit_post', $id ), 'user' => null !== $id && current_user_can( 'edit_user', $id ), default => current_user_can( 'manage_options' ), }; } /** * Whether a core REST deletion is for good, as core's controllers decide * it: true, false for the trash, null where the firewall cannot tell - * another plugin's route, say. An ability decides for itself, so its * deletions are never called either. * * @param ActionDescriptor $action The action. */ private static function permanent( ActionDescriptor $action ): ?bool { $raw = $action->input['force'] ?? false; $force = is_bool( $raw ) ? $raw : is_scalar( $raw ) && rest_sanitize_boolean( (string) $raw ); return match ( $action->entity_type ) { 'post', 'page' => $force || ! self::trashable( (int) $action->entity_id ), 'media' => $force || ! ( defined( 'MEDIA_TRASH' ) && constant( 'MEDIA_TRASH' ) ), 'comment' => $force || ! EMPTY_TRASH_DAYS, 'user', 'term' => true, default => null, }; } /** * Whether core's posts controller would trash this post rather than * delete it: trash is on, the type allows it, and it is not already * there. * * @param int $post_id Post id. */ private static function trashable( int $post_id ): bool { $post = get_post( $post_id ); if ( ! $post instanceof \WP_Post || ! EMPTY_TRASH_DAYS || 'trash' === $post->post_status ) { return false; } // Core's own filter, asked as WP_REST_Posts_Controller asks it. // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Core's hook, not ours. return (bool) apply_filters( "rest_{$post->post_type}_trashable", true, $post ); } /** * The preview's shape. * * @param list $fields Changed fields. * @param Content|null $content The body both ways. * @param Deletion|null $deletion What a deletion removes. * @return Preview */ private static function shaped( array $fields, ?array $content, ?array $deletion = null ): array { return array( 'fields' => $fields, 'content' => $content, 'deletion' => $deletion, // When "current" was read, so the screen can say so. 'read_at' => Time::iso( new DateTimeImmutable( 'now' ) ), ); } /** * One field, both values as text; a current value of null is one that * is not set. * * @param string $name Field name as sent. * @param string $label Its label. * @param mixed $current Value now, null when not set. * @param mixed $proposed Value the agent asked for. * @return Field */ private static function field( string $name, string $label, $current, $proposed ): array { return array( 'name' => $name, 'label' => $label, 'current' => null === $current ? null : self::text( $current ), 'proposed' => self::text( $proposed ), ); } /** * A REST field's value: core also takes `{ "raw": ... }`. * * @param mixed $value Value as sent. * @return mixed */ private static function raw( $value ) { return is_array( $value ) && array_key_exists( 'raw', $value ) ? $value['raw'] : $value; } /** * A value as text: strings as they are, anything else as JSON. * * @param mixed $value Value. */ private static function text( $value ): string { return is_string( $value ) ? $value : (string) wp_json_encode( $value ); } }