From e02bd5e57e86c3006c757fdfdbce299c4e265368 Mon Sep 17 00:00:00 2001
From: Dan Brown <ssddanbrown@googlemail.com>
Date: Thu, 11 Aug 2022 10:49:45 +0100
Subject: [PATCH] Added content security section to the api docs

Related to #3636
---
 app/Http/Controllers/Api/PageApiController.php   |  3 +++
 resources/views/api-docs/index.blade.php         |  1 +
 .../api-docs/parts/getting-started.blade.php     | 16 ++++++++++++++++
 3 files changed, 20 insertions(+)

diff --git a/app/Http/Controllers/Api/PageApiController.php b/app/Http/Controllers/Api/PageApiController.php
index 9749985a5..de729b469 100644
--- a/app/Http/Controllers/Api/PageApiController.php
+++ b/app/Http/Controllers/Api/PageApiController.php
@@ -86,6 +86,9 @@ class PageApiController extends ApiController
      *
      * Pages will always have HTML content. They may have markdown content
      * if the markdown editor was used to last update the page.
+     *
+     * See the "Content Security" section of these docs for security considerations when using
+     * the page content returned from this endpoint.
      */
     public function read(string $id)
     {
diff --git a/resources/views/api-docs/index.blade.php b/resources/views/api-docs/index.blade.php
index 52ad9f8f4..8ce24baae 100644
--- a/resources/views/api-docs/index.blade.php
+++ b/resources/views/api-docs/index.blade.php
@@ -16,6 +16,7 @@
                         <div class="mb-xs"><a href="#listing-endpoints">Listing Endpoints</a></div>
                         <div class="mb-xs"><a href="#error-handling">Error Handling</a></div>
                         <div class="mb-xs"><a href="#rate-limits">Rate Limits</a></div>
+                        <div class="mb-xs"><a href="#content-security">Content Security</a></div>
                     </div>
 
                     @foreach($docs as $model => $endpoints)
diff --git a/resources/views/api-docs/parts/getting-started.blade.php b/resources/views/api-docs/parts/getting-started.blade.php
index edc526971..0d271ec5d 100644
--- a/resources/views/api-docs/parts/getting-started.blade.php
+++ b/resources/views/api-docs/parts/getting-started.blade.php
@@ -179,4 +179,20 @@ API_REQUESTS_PER_MIN=180</code></pre>
     It's generally good practice to limit requests made from your API client, where possible, to avoid
     affecting normal use of the system caused by over-consuming system resources.
     Keep in mind there may be other rate-limiting factors such as web-server & firewall controls.
+</p>
+
+<hr>
+
+<h5 id="content-security" class="text-mono mb-m">Content Security</h5>
+<p>
+    Many of the available endpoints will return content that has been provided by user input.
+    Some of this content may be provided in a certain data-format (Such as HTML or Markdown for page content).
+    Such content is not guaranteed to be safe so keep security in mind when dealing with such user-input.
+    In some cases, the system will apply some filtering to content in an attempt to prevent certain vulnerabilities, but
+    this is not assured to be a bullet-proof defence.
+</p>
+<p>
+    Within its own interfaces, unless disabled, the system makes use of Content Security Policy (CSP) rules to heavily negate
+    cross-site scripting vulnerabilities from user content. If displaying user content externally, it's advised you
+    also use defences such as CSP or the disabling of JavaScript completely.
 </p>
\ No newline at end of file