Merge pull request #9002 from open-sausages/pulls/4/docs-file-access

DOCS Clarified file permission control

docs/en/02_Developer_Guides/00_Model/10_Versioning.md

@@ -27,7 +27,7 @@ Publishing a versioned `DataObject` is equivalent to copying the version from th
 
 You can disable stages if your DataObject doesn't require a published version. This will allow you to keep track of all changes that have been applied to a DataObject and who made them.
 
-### Ownership and relations between DataObject
+### Ownership and relations between DataObject {#ownership}
 
 Typically when publishing versioned DataObjects, it is necessary to ensure that some linked components
 are published along with it. Unless this is done, site content can appear incorrectly published.

docs/en/02_Developer_Guides/14_Files/01_File_Management.md

@@ -50,6 +50,10 @@ UploadField options include:
  - setFolderName() - Name of folder to upload into
  - getValidator() - Get instance of validator to specify custom validation rules
 
+## File permissions {#permissions}
+
+See [File Security](file_security). 
+
 ## File visibility
 
 In order to ensure that assets are made public you should check the following:
@@ -223,7 +227,7 @@ To support this feature the [api:SilverStripe\Assets\AssetControlExtension] prov
 references to physical files, ensuring published assets are accessible, protecting non-published assets,
 and archiving / deleting assets after the final reference has been deleted.
 
-### Configuring file ownership
+### File ownership {#ownership}
 
 When working with files attached to other versioned dataobjects it is necessary to configure ownership
 of these assets from the parent record. This ensures that whenever a Page (or other record type)
@@ -246,6 +250,8 @@ class Page extends SiteTree
 }
 ```
 
+See [Versioned: Ownership](/developer_guides/model/versioned#ownership) for details.
+
 ### Avoid exclusive relationships
 
 Due to the shared nature of assets, it is not recommended to assign any 1-to-many (or exclusive 1-to-1) relationship

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

@@ -2,13 +2,85 @@ summary: Manage access permission to assets
 
 # File Security
 
-## Security overview
+## Overview
 
 File security is an important concept, and is as essential as managing any other piece of data that exists 
 in your system. As pages and dataobjects can be either versioned, or restricted to view by authenticated
 members, it is necessary at times to apply similar logic to any files which are attached to these objects
 in the same way.
 
+## Definitions
+
+There's two dimensions in which to classify how a file can be accessed.
+
+Versioning stage:
+
+ * "Draft file" (default): A file which hasn't been published (default after upload).
+   A subset of "protected file". See [versioning](/developer_guides/model/versioning).
+ * "Published file": A published file (can be protected by further access restrictions).
+   Files are often published indirectly as part
+   of the objects who own them (see [File Ownership](file_management#ownership)).
+ 
+Access restrictions:
+
+ * "Unprotected file" (default): A file without access restrictions.
+ * "Protected file": A file with access restrictions.
+   Note that draft files are always protected, and even published files
+   can be protected if they have access restrictions.
+
+## Permission Model
+
+Like all other objects in SilverStripe, permissions are generally controlled via `can*()` methods,
+for example `canView()` (see [permissions](/developer_guides/security/permissions)).
+
+The permission model defines the following actions:
+
+ * View: Access file metadata in the database.
+ * Edit: Edit file metadata as well as replacing the file content.
+ * Create: Create file metadata and upload file content.
+ * Delete: Delete file metadata and the file content.
+ * Download: Access the file content, but not the file metadata.
+   Usually treated the same as "View".
+
+There's a few rules guiding their access, in descending order of priority:
+
+ * Published and unprotected files can be downloaded by anyone knowing the URL.
+   They bypass any SilverStripe permission checks (served directly by the webserver). 
+ * Access can be restricted by custom `can*()` method implementations on `File`
+   (through [extensions](/developer_guides/extending/extensions)).
+   This logic can overrule any further restrictions below.
+ * Users with "Full administrative rights" (`ADMIN` permission code)
+   have view and edit access by default, regardless of further restrictions below.
+ * Users with "Edit any file" permissions (`FILE_EDIT_ALL` permission code)
+   have edit access by default, regardless of further restrictions below.
+ * View or edit access can be restricted per file or folder through
+   an inherited permissions model similar to page content (through [api:SilverStripe\Security\InheritedPermissionsExtension]).
+   There are four types: "Inherit from parent" (default), "Anyone", "Logged-in users", or "Only these groups".
+ * Protected files (incl. draft files) allow view/edit access when `File::$non_live_permissions` is satisfied.
+   By default, that's configured for anyone with access to any CMS section, or
+   the ability to "view draft content".
+ * Protected files need an "access grant" for the current session
+   in order to download the file (see [User access control](#user-access-control)).
+   While you can technically allow viewing or editing a file without granting
+   access to download it, those aspects are usually bundled together by the file viewing logic. 
+
+Access to create or delete files generally aligns with the edit access described above.
+
+Note that even if the permissions above allow access,
+you need to have access to a mechanism to view or edit file information. 
+Most commonly this is through the "Access to Files section" permission.
+Custom implementations (e.g. APIs or custom file viewers) can have
+further restrictions in your project. 
+
+<div class="warning" markdown="1">
+When implenting your own `canView()` logic through [extensions](/developer_guides/extending/extensions),
+existing unprotected files are not retroactively moved to the protected asset store.
+While those new permissions are honoured in the CMS, protected files through custom `canView()`
+can still be downloaded through a public URL until a `write()` operation is triggered on them.
+</div>  
+
+## Asset stores
+
 Out of the box, SilverStripe comes with two asset stores: a public and a protected one.
 Most operations which act on assets work independently of this mechanism,
 without having to consider whether any specific file is protected or public, but can normally be
@@ -25,7 +97,7 @@ $store->setFromString('My protected content', 'my-folder/my-file.jpg', null, nul
 ]);
 ```
 
-## User access control
+## User access control {#user-access-control}
 
 Access for files is granted on a per-session basis, rather than on a per-member basis, via
 whitelisting accessed assets. This means that access to any protected asset must be made prior to the user