docs: Defend install.sh

Closes #149

README.md

@@ -98,14 +98,24 @@ curl -fsSL https://d2lang.com/install.sh | sh -s --
 You can run the install script with `--dry-run` to see the commands that will be used
 to install without executing them.
 
-To uninstall:
+Or if you have Go installed you can install from source though you won't get the manpage:
+
+```sh
+go install oss.terrastruct.com/d2@latest
+```
+
+To uninstall with the install script:
 
 ```sh
 curl -fsSL https://d2lang.com/install.sh | sh -s -- --uninstall
 ```
 
-For detailed installation docs, with alternative methods and examples for each OS, see
-[./docs/INSTALL.md](./docs/INSTALL.md).
+For detailed installation docs, see [./docs/INSTALL.md](./docs/INSTALL.md).
+We demonstrate alternative methods and examples for each OS.
+
+As well, the functioning of the install script is described in detail to alleviate any
+concern of its use. We recommend using your OS's package manager directly instead for
+improved security but the install script is by no means insecure.
 
 ## D2 as a library
 

ci/fmt.sh

@@ -6,4 +6,7 @@ cd -- "$(dirname "$0")/.."
 if is_changed README.md; then
   sh_c tocsubst --skip 1 README.md
 fi
+if is_changed docs/INSTALL.md; then
+  sh_c tocsubst --skip 1 docs/INSTALL.md
+fi
 ./ci/sub/fmt/make.sh

ci/release/_install.sh

@@ -91,6 +91,9 @@ note: Deleting the unarchived releases will cause --uninstall to stop working.
 
 You can rerun install.sh to update your version of D2. install.sh will avoid reinstalling
 if the installed version is the latest unless --force is passed.
+
+See https://github.com/terrastruct/d2/blob/master/docs/INSTALL.md#security for
+documentation on its security.
 EOF
 }
 
@@ -506,4 +509,7 @@ brew() {
   HOMEBREW_NO_INSTALL_CLEANUP=1 HOMEBREW_NO_AUTO_UPDATE=1 command brew "$@"
 }
 
+# The main function does more than provide organization. It provides robustness in that if
+# the install script was to only partial download into sh, sh will not execute it because
+# main is not invoked until the very last byte.
 main "$@"

ci/release/changelogs/next.md

@@ -17,7 +17,7 @@
 - `-b/--bundle` flag to `d2` now works and bundles all image assets directly as base64
   data urls. [#278](https://github.com/terrastruct/d2/pull/278)
 
-#### Improvements 🔧
+#### Improvements 🧹
 
 - Local images can now be included, e.g. `icon: ./my_img.png`.
   [#146](https://github.com/terrastruct/d2/issues/146)

ci/release/changelogs/template.md

@@ -1,5 +1,5 @@
 #### Features 🚀
 
-#### Improvements 🔧
+#### Improvements 🧹
 
 #### Bugfixes 🔴

docs/INSTALL.md

@@ -3,13 +3,12 @@
 You may install D2 through any of the following methods.
 
 <!-- toc -->
-
-- [install.sh](#installsh)
-- [macOS (Homebrew)](#macos-homebrew)
-- [Standalone](#standalone)
-- [From source](#from-source)
-
-<!-- tocstop -->
+- <a href="#installsh" id="toc-installsh">install.sh</a>
+  - <a href="#security" id="toc-security">Security</a>
+- <a href="#macos-homebrew" id="toc-macos-homebrew">macOS (Homebrew)</a>
+- <a href="#standalone" id="toc-standalone">Standalone</a>
+- <a href="#from-source" id="toc-from-source">From source</a>
+- <a href="#coming-soon" id="toc-coming-soon">Coming soon</a>
 
 ## install.sh
 
@@ -31,6 +30,37 @@ methods:
 curl -fsSL https://d2lang.com/install.sh | sh -s -- --help
 ```
 
+### Security
+
+The install script is not the most secure way to install d2. We recommend that if
+possible, you use your OS's package manager directly or install from source with `go` as
+described below.
+
+But this does not mean the install script is insecure. There is no major flaw that
+the install script is more vulnerable to than any other method of manual installation.
+The most secure installation method involves a second independent entity, i.e your OS
+package repos or Go's proxy server.
+
+We're careful shell programmers and are aware of the many footguns of the unix shell. Our
+script was written carefully and with detail. For example, it is not vulnerable to partial
+execution and the entire script runs with `set -eu` and very meticulous quoting.
+
+It follows the XDG standards, installs d2 properly into a unix hierarchy path (defaulting
+to /usr/local though you can use ~/.local to avoid sudo if you'd like) and allows for easy
+uninstall.
+
+Some other niceties are that it'll tell you if you need to adjust `$PATH` or `$MANPATH` to
+access d2 and its manpages. It can also install
+[TALA](https://github.com/terrastruct/tala) for you with `--tala`. You can also use it to
+install a specific version of `d2` with `--version`. Run it with `--help` for more more
+detailed docs on its various options and features.
+
+If you're still concerned, remember you can run with `--dry-run` to avoid executing
+anything permanent.
+
+The install script does not yet verify any signature on the downloaded release
+but that is coming soon. [#315](https://github.com/terrastruct/d2/issues/315)
+
 ## macOS (Homebrew)
 
 If you're on macOS, you can install with `brew`.
@@ -86,6 +116,14 @@ You can always install from source:
 go install oss.terrastruct.com/d2@latest
 ```
 
+To install a proper release from source clone the repository and then:
+
+```sh
+./ci/release/build.sh --install
+# To uninstall:
+# ./ci/release/build.sh --uninstall
+```
+
 ## Coming soon
 
 - Docker image

install.sh

@@ -576,6 +576,9 @@ note: Deleting the unarchived releases will cause --uninstall to stop working.
 
 You can rerun install.sh to update your version of D2. install.sh will avoid reinstalling
 if the installed version is the latest unless --force is passed.
+
+See https://github.com/terrastruct/d2/blob/master/docs/INSTALL.md#security for
+documentation on its security.
 EOF
 }
 
@@ -991,4 +994,7 @@ brew() {
   HOMEBREW_NO_INSTALL_CLEANUP=1 HOMEBREW_NO_AUTO_UPDATE=1 command brew "$@"
 }
 
+# The main function does more than provide organization. It provides robustness in that if
+# the install script was to only partial download into sh, sh will not execute it because
+# main is not invoked until the very last byte.
 main "$@"