Improve docs around when to use Media Library vs File Attachments

Author: LukeTowers

backend/forms.md

@@ -1011,6 +1011,8 @@ Option | Description
 
 > **NOTE:** Unlike the [Media Finder FormWidget](#media-finder), the File Upload FormWidget uses [database file attachments](../database/attachments); so the field name must match a valid `attachOne` or `attachMany` relationship on the Model associated with the Form. **IMPORTANT:** Having a database column with the name used by this field type (i.e. a database column with the name of an existing `attachOne` or `attachMany` relationship) **will** cause this FormWidget to break. Use database columns with the Media Finder FormWidget and file attachment relationships with the File Upload FormWidget.
 
+> **Security:** File attachments are public by default. For sensitive files that require access control, set `'public' => false` in your model's attachment relationship configuration. See [Protected Attachments](../database/attachments#protected-attachments) for more information.
+
 By default, the File Upload FormWidget only allows a limited set of file extensions. You can extend this list by adding a `fileDefinitions` config in `config/cms.php` file.
 See [Allowed file types](../setup/configuration#allowed-file-types) for more information.
 
@@ -1086,6 +1088,8 @@ Option | Description
 
 > **NOTE:** Unlike the [File Upload FormWidget](#file-upload), the Media Finder FormWidget stores its data as a string representing the path to the image selected within the Media Library.
 
+> **Warning:** Files selected from the Media Library are **publicly accessible via direct URL** without any authentication or access control. Do not use the Media Finder for sensitive or private files. For files requiring access control, use the [File Upload FormWidget](#file-upload) with [Protected Attachments](../database/attachments#protected-attachments) instead.
+
 ### Nested Form
 
 `nestedform` - renders a nested form as the contents of this field and returns the form data as an array.

cms/mediamanager.md

@@ -6,6 +6,8 @@ By default Media Manager works with the storage/app/media subdirectory of the in
 
 Please note that after you change Media Manager configuration, you should reset its cache. You can do that with pressing the **Refresh** button in the Media Manager toolbar.
 
+> **Warning:** All files uploaded to the Media Library are **publicly accessible** via direct URL without any authentication. The Media Manager is designed for public assets like theme images, videos, and content that should be accessible to all website visitors. **Do not use the Media Library for sensitive files, user documents, or private content.** For files that require access control, use [File Attachments](../database/attachments) with the `public => false` option instead.
+
 ## Configuring Amazon S3 access
 
 To use Amazon S3 with Winter CMS, you should create S3 bucket, folder in the bucket and API user.
@@ -243,7 +245,7 @@ Parameter | Value
 
 ### Allowing more specific file extensions
 
-By default, the Media Manager only allows a limited set of file extensions. You can extend this list by adding a `fileDefinitions` config in `config/cms.php` file.  
+By default, the Media Manager only allows a limited set of file extensions. You can extend this list by adding a `fileDefinitions` config in `config/cms.php` file.
 See [Allowed file types](../setup/configuration#allowed-file-types) for more information.
 
 ## Events
@@ -279,6 +281,40 @@ Event::listen('media.file.rename', function ($widget, $originalPath, $newPath) {
 });
 ```
 
+## Security considerations
+
+### Public access by default
+
+All files stored in the Media Library are publicly accessible via direct URL. This means:
+
+- **No authentication required**: Anyone who knows or can guess the file URL can access it
+- **No permission checks**: Backend user permissions do not affect access to media files
+- **Direct browser access**: Files can be accessed directly without going through Winter CMS
+
+For local storage, media files are served from `/storage/app/media/` and configured in your web server to be publicly accessible (see [Server Configuration](../setup/configuration) for details).
+
+### When to use Media Manager
+
+The Media Manager is appropriate for:
+
+- Theme assets (images, videos, fonts)
+- Public website content (blog images, product photos, downloadable brochures)
+- Files that are meant to be embedded in CMS pages or layouts
+- Content that should be accessible to all website visitors
+- Files that may be referenced from multiple places in your application
+
+### When NOT to use Media Manager
+
+**Do not use the Media Manager for:**
+
+- User-uploaded documents that should be private
+- Files containing sensitive or confidential information
+- Content that requires authentication or authorization
+- User-specific files (profile pictures, personal documents)
+- Files subject to privacy regulations (GDPR, CCPA, etc.)
+
+For these scenarios, use [File Attachments](../database/attachments) with the `public => false` option instead.
+
 ## Troubleshooting
 
 The most common issue with using remote services is the SSL connection problem. If you get SSL errors, make sure that your server has fresh SSL certificates of public Certificate Authorities (CA).

database/attachments.md

@@ -6,6 +6,8 @@ Winter CMS provides a few different ways to manage files depending on your needs
 
 When using the `System\Models\File` model, you are able to configure the disk and paths that are used to store and retrieve the files managed by that model by modifying the `storage.uploads` setting in the [`config/cms.php` file](https://github.com/wintercms/winter/blob/develop/config/cms.php#L317).
 
+> **Warning:** File attachments are **public by default** and accessible via direct URL without authentication. To protect sensitive files, you **must explicitly set** `'public' => false` in your attachment configuration. For truly public content that doesn't need database tracking (like theme assets), consider using the [Media Manager](../cms/mediamanager) instead.
+
 ## File attachments
 
 Models can support file attachments using a subset of the [polymorphic relationship](../database/relations#polymorphic-relations). The `$attachOne` or `$attachMany` relations are designed for linking a file to a database record called "attachments". In almost all cases the `System\Models\File` model is used to safekeep this relationship where reference to the files are stored as records in the `system_files` table and have a polymorphic relation to the parent model.
@@ -30,17 +32,40 @@ public $attachMany = [
 
 > **NOTE:** If you have a column in your model's table with the same name as the attachment relationship it will not work. Attachments and the FileUpload FormWidget work using relationships, so if there is a column with the same name present in the table itself it will cause issues.
 
-Protected attachments are uploaded to the File Upload disk's **uploads/protected** directory which is not accessible for the direct access from the Web. A protected file attachment is defined by setting the *public* argument to `false`:
+### Protected attachments
+
+Protected attachments provide access control for sensitive files. Unlike public attachments, protected files cannot be accessed via direct URL and require backend authentication.
+
+**Key differences between public and protected attachments:**
+
+- **Storage location**: Protected files are stored in `storage/app/uploads/protected/` instead of `storage/app/uploads/public/`
+- **Web server access**: The protected directory is not configured for direct web access in server configuration
+- **Authentication**: Protected files can only be accessed by authenticated backend users with appropriate permissions
+- **URL access**: Protected files are served through Winter CMS's protected file route, not directly from the filesystem
+
+**When to use protected attachments:**
+
+- User-uploaded documents containing sensitive information
+- Files subject to privacy regulations (GDPR, CCPA, etc.)
+- Content that requires authentication or authorization
+- User-specific files (contracts, invoices, medical records)
+- Any file that should not be publicly accessible
+
+**Defining a protected attachment:**
+
+Set the `public` argument to `false` in your attachment configuration:
 
 ```php
 public $attachOne = [
-    'avatar' => [
+    'confidential_document' => [
         \System\Models\File::class,
         'public' => false,
     ],
 ];
 ```
 
+For comparison with other file management approaches, see the [Media Manager security considerations](../cms/mediamanager#security-considerations).
+
 ### Creating new attachments
 
 For singular attach relations (`$attachOne`), you may create an attachment directly via the model relationship, by setting its value using the `Input::file` method, which reads the file data from an input upload.
@@ -74,17 +99,19 @@ foreach ($files as $file) {
 }
 ```
 
-Alternatively, you can prepare a File model before hand, then manually associate the relationship later. Notice the `is_public` attribute must be set explicitly using this approach.
+Alternatively, you can prepare a File model before hand, then manually associate the relationship later. When creating files this way, the `is_public` attribute must be set explicitly, as it won't automatically inherit from the attachment relationship configuration.
 
 ```php
 $file = new System\Models\File;
 $file->data = Input::file('file_input');
-$file->is_public = true;
+$file->is_public = true; // Set to false for protected files
 $file->save();
 
 $model->avatar()->add($file);
 ```
 
+> **Note:** Set `is_public` to `true` for publicly accessible files or `false` for protected files that require authentication. When using the relationship's `create()` method (shown earlier), the `is_public` value is automatically determined from the attachment configuration's `public` option.
+
 You can also add a file from a URL. To work this method, you need install cURL PHP Extension.
 
 ```php

setup/configuration.md

@@ -68,6 +68,13 @@ location ~ ^/humans\.txt { try_files $uri /index.php; }
 location ~ /\.(?!well-known).* { deny all; }
 
 ## Let nginx return 404 if static file not exists
+## These paths expose PUBLIC file storage directories:
+## - /storage/app/uploads/public: Public file attachments (attachments with 'public' => true)
+## - /storage/app/media: Media Manager files (always public, no access control)
+## - /storage/app/resized: Dynamically resized images (public)
+## - /storage/temp/public: Public temporary files
+## NOTE: /storage/app/uploads/protected is intentionally NOT listed here - those files
+##       require authentication and are served through Winter CMS, not directly by nginx
 location ~ ^/storage/app/uploads/public { try_files $uri 404; }
 location ~ ^/storage/app/media { try_files $uri 404; }
 location ~ ^/storage/app/resized { try_files $uri 404; }
@@ -123,6 +130,12 @@ Paste the following code in the editor and change the **host address** and  `ser
 $HTTP["host"] =~ "domain.example.com" {
     server.document-root = "/var/www/example/"
 
+    # Public file storage paths (publicly accessible without authentication):
+    # - /storage/app/uploads/public: Public file attachments
+    # - /storage/app/media: Media Manager files (always public)
+    # - /storage/app/resized: Dynamically resized images
+    # - /storage/temp/public: Public temporary files
+    # Note: /storage/app/uploads/protected is NOT exposed here
     url.rewrite-once = (
         "^/(plugins|modules/(system|backend|cms))/(([\w-]+/)+|/|)assets/([\w-]+/)+[-\w^&'@{}[\],$=!#().%+~/ ]+\.(jpg|jpeg|gif|png|svg|swf|avi|mpg|mpeg|mp3|flv|ico|css|js|woff|ttf)(\?.*|)$" => "$0",
         "^/(system|themes/[\w-]+)/assets/([\w-]+/)+[-\w^&'@{}[\],$=!#().%+~/ ]+\.(jpg|jpeg|gif|png|svg|swf|avi|mpg|mpeg|mp3|flv|ico|css|js|woff|ttf)(\?.*|)$" => "$0",
@@ -146,6 +159,14 @@ If your webserver is running Internet Information Services (IIS) you can use the
     <system.webServer>
         <rewrite>
             <rules>
+                <!--
+                    Public file storage paths (publicly accessible without authentication):
+                    - /storage/app/uploads/public: Public file attachments
+                    - /storage/app/media: Media Manager files (always public)
+                    - /storage/app/resized: Dynamically resized images
+                    - /storage/temp/public: Public temporary files
+                    Note: /storage/app/uploads/protected is NOT exposed here
+                -->
                 <rule name="Winter CMS to handle all non-whitelisted URLs" stopProcessing="true">
                     <match url="^index.php" negate="true" />
                     <conditions logicalGrouping="MatchAll">