DOCS Recommend moving .protected out of webroot

Note that it's currently unclear whether Silverstripe Cloud or CWP support this,
but it shouldn't block us from recommend this in the open source project.
It's documented in the "server requirements", which should make it pretty
clear that this requires you to have control over server configuration (or check with those that have).

See https://github.com/silverstripe/silverstripe-framework/issues/7710

docs/en/00_Getting_Started/00_Server_Requirements.md

@@ -64,7 +64,7 @@ dynamically generated whitelist based on the `File.allowed_extensions` setting
 This whitelist uses the same defaults configured through file upload
 through SilverStripe, so is considered a second line of defence.
 
-### Secure Assets
+### Secure Assets {#secure-assets}
 
 Files can be kept in draft stage,
 and access restricted to certain user groups.
@@ -76,6 +76,32 @@ are routed to PHP by default when using Apache, through `public/assets/.htaccess
 If you are using another webserver, please follow our guides to ensure a secure setup.
 See [Developer Guides: File Security](/developer_guides/files/file_security) for details.
 
+For additional security, we recommend moving the `.protected/` folder out of `public/assets/`.
+This removes the possibility of a misconfigured webserver accidentally exposing
+these files under URL paths, and forces read access via PHP.
+
+This can be configured via [.env](/getting_started/environment_management) variable,
+relative to the `index.php` location.
+
+```
+SS_PROTECTED_ASSETS_PATH="../.protected/"
+```
+
+The resulting folder structure will look as follows:
+
+```
+.protected/
+  <hash>/my-protected-file.txt
+public/
+  index.php
+  assets/
+    my-public-file.txt
+vendor/
+app/
+```
+
+Don't forget to include this additional folder in any syncing and backup processes!
+
 
 ### Web Worker Concurrency
 

docs/en/00_Getting_Started/04_Directory_Structure.md

@@ -17,6 +17,7 @@ Directory            | Description
 ---------            | -----------
 `public/`            | Webserver public webroot
 `public/assets/`     | Images and other files uploaded via the SilverStripe CMS. You can also place your own content inside it, and link to it from within the content area of the CMS.
+`public/assets/.protected/` | Default location for [protected assets](/developer_guides/files/file_security)
 `public/_resources/` | Exposed public files added from modules. Folders within this parent will match that of the source root location (this can be altered by configuration). 
 `vendor/`            | SilverStripe modules and other supporting libraries (the framework is in `vendor/silverstripe/framework`)
 `themes/`            | Standard theme installation location

docs/en/02_Developer_Guides/09_Security/04_Secure_Coding.md

@@ -509,26 +509,36 @@ standard PHP way. See [casting](/developer_guides/model/data_types_and_casting).
 
 ## Filesystem
 
-### Don't script-execution in /assets
+### Don't allow script-execution in /assets
 
 Please refer to the article on [file security](/developer_guides/files/file_security)
 for instructions on how to secure the assets folder against malicious script execution.
 
-### Don't allow access to YAML files
+### Don't run Silverstripe in the webroot
 
-YAML files are often used to store sensitive or semi-sensitive data for use by 
+Silverstripe routes all execution through a [public/ subfolder](/getting_started/directory_structure))
-SilverStripe, such as configuration files. We block access to any files
+by default. This enables you to keep application code and configuration outside of webserver routing.
-with a `.yml` or `.yaml` extension through the default web server rewriting rules.
+But since this was introduced after the 4.0, there's a fallback `.htaccess` file in place
-If you need users to access files with this extension,
+which allows you to set the webroot to the project root. Don't rely on this, since it increases your security surface.
-you can bypass the rules for a specific directory.
-Here's an example for a `.htaccess` file used by the Apache web server:
 
 ```
-<Files ~ "\.ya?ml$">
+.htaccess <- fallback, shouldn't be used
-    Require all granted
+public/ <- this should be your webroot
-</Files>
+  .htaccess
+  index.php
+app/
+  _config/
+    secrets.yml <- this isn't routed if public/ is your webroot
 ```
 
+### Don't place protected files in the webroot
+
+Protected files are stored in `public/assets/.protected` by default
+(assuming you're using the [public/ subfolder](/getting_started/directory_structure)).
+While default configuration is in place to avoid the webserver serving these files,
+we recommend moving them out of the webroot altogether -
+see [Server Requirements: Secure Assets](/getting_started/server_requirements#secure-assets).
+
 ### User uploaded files
 
 Certain file types are by default excluded from user upload. html, xhtml, htm, and xml files may have embedded,

docs/en/02_Developer_Guides/14_Files/03_File_Security.md

@@ -439,20 +439,30 @@ SilverStripe\ORM\DataObject:
   AssetControl: null
 ```
 
-### Configuring: Web server settings
+## Webserver Configuration
+
+### Protected files location
+
+Protected files are stored in `public/assets/.protected` by default
+(assuming you're using the [public/ subfolder](/getting_started/directory_structure)).
+While default configuration is in place to avoid the webserver serving these files,
+we recommend moving them out of the webroot altogether -
+see [Server Requirements: Secure Assets](/getting_started/server_requirements#secure-assets).
+
+### Config templates
 
 If the default server configuration is not appropriate for your specific environment, then you can
-further customise the .htaccess or web.config by editing one or more of the below:
+further customise the `.htaccess` or `web.config` by editing one or more of the below:
 
 * `PublicAssetAdapter_HTAccess.ss`: Template for public permissions on the Apache server.
 * `PublicAssetAdapter_WebConfig.ss`: Template for public permissions on the IIS server.
 * `ProtectedAssetAdapter_HTAccess.ss`: Template for the protected store on the Apache server (should deny all requests).
 * `ProtectedAssetAdapter_WebConfig.ss`: Template for the protected store on the IIS server (should deny all requests).
 
-Each of these files will be regenerated on ?flush, so it is important to ensure that these files are
+Each of these files will be regenerated on `?flush`, so it is important to ensure that these files are
 overridden at the template level, not via manually generated configuration files.
 
-#### Configuring Web Server: Apache server
+#### Apache
 
 In order to ensure that public files are served correctly, you should check that your `assets/.htaccess`
 bypasses PHP requests for files that do exist. The default template
@@ -486,7 +496,7 @@ For instance your server configuration should look similar to the below:
 The `php_admin_flag` will protect against uploaded `.htaccess` files accidentally re-enabling script
 execution within the assets directory.
 
-#### Configuring Web Server: Windows IIS 7.5+
+#### Windows IIS 7.5+
 
 Configuring via IIS requires the Rewrite extension to be installed and configured properly.
 Any rules declared for the assets folder should be able to dynamically serve up existing files,
@@ -508,7 +518,7 @@ The default rule for IIS is as below (only partial configuration displayed):
 You will need to make sure that the `allowOverride` property of your root web.config is not set
 to false, to allow these to take effect.
 
-#### Configuring Web Server: Other server types
+#### Other server types
 
 If using a server configuration which must be configured outside of the web or asset root, you
 will need to make sure you manually configure these rules.

docs/en/02_Developer_Guides/14_Files/04_File_Storage.md

@@ -122,7 +122,8 @@ It leaves out the `.protected/` folder, and leaves that to SilverStripe's integr
 `http://www.example.com/assets/my-protected-folder/b63923d8d4/my-protected-file.jpg`.
 
 For more information on how protected files are stored see the [file security](/developer_guides/files/file_security)
-section.
+section. We recommend moving this folder outside of the webroot,
+see [Server Requirements: Secure Assets](/getting_started/server_requirements#secure-assets).
 
 ## Versioned file paths