From 5a2d0f04377764f67a46c35f6ee267ee5b0e718b Mon Sep 17 00:00:00 2001
From: epriestley <git@epriestley.com>
Date: Mon, 15 Apr 2019 11:58:51 -0700
Subject: [PATCH] Update documentation for "uri.allowed-protocols"

Summary: See <https://discourse.phabricator-community.org/t/download-tasks-and-others-as-excel-throw-exception/>.

Test Plan: Read config.

Reviewers: amckinley, avivey

Reviewed By: avivey

Subscribers: avivey

Differential Revision: https://secure.phabricator.com/D20430
---
 .../PhabricatorSecurityConfigOptions.php      | 24 ++++++++++++++-----
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/src/applications/config/option/PhabricatorSecurityConfigOptions.php b/src/applications/config/option/PhabricatorSecurityConfigOptions.php
index 50fc24a85d..d5557e3688 100644
--- a/src/applications/config/option/PhabricatorSecurityConfigOptions.php
+++ b/src/applications/config/option/PhabricatorSecurityConfigOptions.php
@@ -163,14 +163,26 @@ EOTEXT
           'mailto' => true,
         ))
         ->setSummary(
-          pht('Determines which URI protocols are auto-linked.'))
+          pht(
+            'Determines which URI protocols are valid for links and '.
+            'redirects.'))
         ->setDescription(
           pht(
-            "When users write comments which have URIs, they'll be ".
-            "automatically linked if the protocol appears in this set. This ".
-            "whitelist is primarily to prevent security issues like ".
-            "%s URIs.",
-            'javascript://'))
+            'When users write comments which have URIs, they will be '.
+            'automatically turned into clickable links if the URI protocol '.
+            'appears in this set.'.
+            "\n\n".
+            'This set of allowed protocols is primarily intended to prevent '.
+            'security issues with "javascript:" and other potentially '.
+            'dangerous URI handlers.'.
+            "\n\n".
+            'This set is also used to enforce valid redirect URIs. '.
+            'Phabricator will refuse to issue a HTTP "Location" redirect to a '.
+            'URI with a protocol not on this set.'.
+            "\n\n".
+            'Usually, "http" and "https" should be present in this set. If '.
+            'you remove one or both protocols, some Phabricator features '.
+            'which rely on links or redirects may not work.'))
         ->addExample("http\nhttps", pht('Valid Setting'))
         ->setLocked(true),
       $this->newOption(