From 0db27ee2d69d2b35f2bc0b8fef2f6ae04b755835 Mon Sep 17 00:00:00 2001
From: Guangcong Luo <guangcongluo@gmail.com>
Date: Mon, 15 Nov 2021 18:18:42 -0500
Subject: [PATCH] Improve documentation of $outPrefix

---
 lib/dispatcher.lib.php | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/lib/dispatcher.lib.php b/lib/dispatcher.lib.php
index 08df2b119..9b5eafc72 100644
--- a/lib/dispatcher.lib.php
+++ b/lib/dispatcher.lib.php
@@ -4,7 +4,30 @@ class ActionDispatcher {
 	private $reqs;
 	private $multiReqs = false;
 	private $reqData;
-	private $outPrefix = ']'; // JSON output should not be valid JavaScript
+	/**
+	 * API request output should not be valid JavaScript.
+	 *
+	 * This is to protect against a CSRF-like attack. Imagine you have an API:
+	 *
+	 *     https://example.com/getmysecrets.json
+	 *
+	 * Which returns:
+	 *
+	 *     {"yoursecrets": [1, 2, 3]}
+	 *
+	 * An attacker could trick a user into visiting a site overriding the
+	 * Array or Object constructor, and then containing:
+	 *
+	 *     <script src="https://example.com/getmysecrets.json"></script>
+	 *
+	 * This could let them steal the secrets. In modern times, browsers
+	 * are protected against this kind of attack, but our `]` adds some
+	 * safety for older browsers.
+	 *
+	 * Adding `]` to the beginning makes sure that the output is a syntax
+	 * error in JS, so treating it as a JS file will simply crash and fail.
+	 */
+	private $outPrefix = ']';
 	private $outArray = array();
 
 	public function __construct($handlers) {