403 ) ); } return self::verify_nonce( $request ); } /** * MANAGE permission: `manage_aipt_settings` + nonce. * * @param WP_REST_Request $request Request object. * @return true|WP_Error */ public static function check_permissions_manage( $request ) { if ( ! current_user_can( RestConstants::CAP_MANAGE ) ) { return new WP_Error( 'rest_forbidden', __( 'You need permission to manage settings to do this.', 'ai-product-tools' ), array( 'status' => 403 ) ); } return self::verify_nonce( $request ); } /** * Verify the `wp_rest` nonce from the request (header first, then * `_wpnonce`), exactly like {@see \AIPT\Core\ContentReview\ContentReviewController::verify_nonce()}. * * A GET request is a read and never needs the nonce — this callback is * shared across mixed-method routes (several POST/PUT/DELETE routes * reuse `check_permissions_read()`), so the exemption lives here rather * than in each caller. For any other method, the nonce is required only * from a cookie-authenticated request: an Application-Password/Basic-Auth * (or other non-cookie) client is already authenticated and has no way * to ever obtain one, exactly like WP core's own write routes * ({@see \AIPT\Utils\RestNonceGuard}). * * @param WP_REST_Request $request Request object. * @return true|WP_Error */ protected static function verify_nonce( $request ) { if ( $request instanceof WP_REST_Request && 'GET' === $request->get_method() ) { return true; } return \AIPT\Utils\RestNonceGuard::check( $request, __( 'Invalid or missing security nonce.', 'ai-product-tools' ) ); } /** * `{success:true,data}` envelope. * * @param mixed $data Response payload. * @param int $status HTTP status. * @return WP_REST_Response */ protected static function success( $data, int $status = 200 ): WP_REST_Response { return new WP_REST_Response( array( 'success' => true, 'data' => $data ), $status ); } /** * A `WP_Error` carrying `{status}` plus any extra data keys, matching * every other Blueprint error response's shape. * * @param string $code Error code (prefixed `aipt_blueprint_` by convention, not enforced here). * @param string $message Translated message. * @param int $status HTTP status. * @param array $extra Additional response data merged after `status`. * @return WP_Error */ protected static function error( string $code, string $message, int $status, array $extra = array() ): WP_Error { return new WP_Error( $code, $message, array( 'status' => $status ) + $extra ); } /** * Convert a store's MySQL UTC datetime string to ISO 8601 * (`gmdate('c', strtotime($value.' UTC'))`). * * @param string $mysql_utc MySQL UTC datetime, or ''/null-ish for "unset". * @return string ISO-8601 string, or '' when $mysql_utc is empty. */ protected static function isoDate( string $mysql_utc ): string { if ( '' === $mysql_utc ) { return ''; } $timestamp = strtotime( $mysql_utc . ' UTC' ); return false !== $timestamp ? gmdate( 'c', $timestamp ) : ''; } /** * `{id,name}` summary for a user id, or null for an unset (0) id or an * id that no longer resolves to a user. * * @param int $user_id User id. * @return array{id:int,name:string}|null */ protected static function userSummary( int $user_id ): ?array { if ( $user_id <= 0 ) { return null; } $user = get_userdata( $user_id ); if ( false === $user ) { return null; } return array( 'id' => $user_id, 'name' => (string) $user->display_name ); } /** * Clamp a definition's `sources.allowedDomains` for the acting user: a * web page source's reach is a settings-manager decision * (CAP_MANAGE), so a save by anyone else must never widen it, no * matter what the submitted definition asked for. * * @param array $definition Definition about to be saved (already normalized). * @param array|null $current_definition The definition this one replaces (update), or null (create/copy with nothing before it). * @return array $definition, with `sources.allowedDomains` replaced by the safe value when the actor lacks CAP_MANAGE. */ protected static function enforceAllowedDomains( array $definition, ?array $current_definition ): array { if ( current_user_can( RestConstants::CAP_MANAGE ) ) { return $definition; } $safe_domains = array(); if ( null !== $current_definition && isset( $current_definition['sources']['allowedDomains'] ) && is_array( $current_definition['sources']['allowedDomains'] ) ) { $safe_domains = $current_definition['sources']['allowedDomains']; } $definition['sources']['allowedDomains'] = $safe_domains; return $definition; } /** * Sanitized opaque keyset cursor from a request's `cursor` param. * * @param WP_REST_Request $request Request object. * @return string */ protected static function parseCursor( WP_REST_Request $request ): string { $cursor = $request->get_param( 'cursor' ); return is_string( $cursor ) ? sanitize_text_field( wp_unslash( $cursor ) ) : ''; } /** * Sanitized page-size limit from a request's `limit` param, bounded to * [1, RestConstants::MAX_LIMIT]. * * @param WP_REST_Request $request Request object. * @param int $default Default when `limit` is absent or non-numeric. * @return int */ protected static function parseLimit( WP_REST_Request $request, int $default = RestConstants::DEFAULT_LIMIT ): int { $raw = $request->get_param( 'limit' ); $int = is_numeric( $raw ) ? (int) $raw : $default; return max( 1, min( RestConstants::MAX_LIMIT, $int > 0 ? $int : $default ) ); } }