Added content security section to the api docs

Related to #3636

diff --git a/app/Http/Controllers/Api/PageApiController.php b/app/Http/Controllers/Api/PageApiController.php
index 9749985a52214cecbec3ee8cfecf9d0bc2b84e54..de729b469b3e7f12f7ee5d7e762d17566366995c 100644 (file)
--- 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 52ad9f8f4aa351d70acc8fabeaface4ca5ae83ef..8ce24baaec5e8e447d541f7010ffcc2420c5fe5b 100644 (file)
--- 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 edc526971e214e146321ddb188f185d0fa625518..0d271ec5dac7cfc5de72bc49b01e2ca90a6c6538 100644 (file)
--- 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